Upload folder using huggingface_hub

.golangci.yaml

@@ -0,0 +1,68 @@
+# yaml-language-server: $schema=https://golangci-lint.run/jsonschema/golangci.jsonschema.json
+version: "2"
+linters:
+  default: none
+  enable:
+    - bodyclose
+    - errcheck
+    - govet
+    - ineffassign
+    - misspell
+    - nolintlint
+    - sloglint
+    - staticcheck
+    - unconvert
+    # FIXME: re-enable following linters
+    #- unparam
+    #- unused
+    - whitespace
+    #- wsl
+  settings:
+    misspell:
+      locale: US
+    nolintlint:
+      require-specific: true
+    revive:
+      confidence: 0
+    staticcheck:
+      checks:
+        - "all"
+        - "-QF1008"
+        - "-SA1019" # https://staticcheck.dev/docs/checks/#SA1019
+        # FIXME: re-enable the following checks
+        - "-ST1003"
+        - "-ST1016"
+  exclusions:
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
+    paths:
+      - collector/benthos/internal
+      - third_party$
+      - builtin$
+      - examples$
+formatters:
+  enable:
+    - gci
+    - gofmt
+    - gofumpt
+    - goimports
+  settings:
+    gci:
+      sections:
+        - standard
+        - default
+        - prefix(github.com/openmeterio/openmeter)
+    goimports:
+      local-prefixes:
+        - github.com/openmeterio/openmeter
+  exclusions:
+    generated: lax
+    paths:
+      - collector/benthos/internal
+      - third_party$
+      - builtin$
+      - examples$

.goreleaser.yaml

@@ -0,0 +1,45 @@
+# This is an example .goreleaser.yml file with some sensible defaults.
+# Make sure to check the documentation at https://goreleaser.com
+project_name: openmeter
+
+dist: build/dist
+
+gomod:
+  proxy: true
+
+before:
+  hooks:
+    - go mod tidy
+builds:
+  - env:
+      - CGO_ENABLED=0
+    main: .
+    goos:
+      - linux
+      - windows
+      - darwin
+
+archives:
+  - format: tar.gz
+    # this name template makes the OS and Arch compatible with the results of uname.
+    name_template: >-
+      {{ .ProjectName }}_
+      {{- title .Os }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "386" }}i386
+      {{- else }}{{ .Arch }}{{ end }}
+      {{- if .Arm }}v{{ .Arm }}{{ end }}
+    # use zip for windows archives
+    format_overrides:
+      - goos: windows
+        format: zip
+checksum:
+  name_template: "checksums.txt"
+snapshot:
+  name_template: "{{ incpatch .Version }}-next"
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - "^docs:"
+      - "^test:"

.grype/config.yaml

@@ -0,0 +1,5 @@
+
+ignore:
+  # Nats server admin api authorization bypass: https://github.com/advisories/ghsa-fhg8-qxh5-7q3w
+  # This is not an issue, as we never start a nats server in our codebase
+  - vulnerability: GHSA-fhg8-qxh5-7q3w

.hfignore

@@ -0,0 +1,40 @@
+.git/
+.devenv/
+.direnv/
+.env.local
+.pre-commit-config.yaml
+build/
+config.yaml
+tmp/
+.tmp.*
+.DS_Store
+go.work
+go.work.sum
+__debug_bin*
+openmeter.log
+.gocache
+.gomodcache
+.claude/
+CLAUDE.local.md
+api/v3/templates/chi-middleware.tmpl
+.codegraph/
+node_modules/
+dist/
+.agents/
+.vscode/
+.github/
+.spectral.yaml
+.syft.yaml
+.fossa.yaml
+.editorconfig
+.coderabbit.yaml
+.golangci.yaml
+.golangci-fast.yaml
+.goreleaser.yaml
+.mcp.json
+.semgrepignore
+atlas.hcl
+flake.lock
+flake.nix
+justfile
+Makefile

.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": ["serve", "--mcp"]
+    }
+  }
+}

.nvmrc

@@ -0,0 +1 @@
+v26.4.0

.semgrepignore

@@ -0,0 +1,9 @@
+api/client/python/src/openmeter/_serialization.py
+**/*_test.go
+
+# These are only included due to bugous //nosemgrep support in current version, please remove them once the semgrep has been upgraded
+
+openmeter/billing/service/seq.go
+collector/benthos/input/otel_log.go
+openmeter/productcatalog/feature/connector.go
+openmeter/watermill/driver/kafka/broker.go

.spectral.yaml

@@ -0,0 +1,9 @@
+extends: [[spectral:oas, recommended]]
+rules:
+  info-contact: off
+
+  # Disabled due to TypeSpec conversion
+  oas3-valid-schema-example: off
+  no-$ref-siblings: off
+  path-params: off
+  oas3-unused-component: off

.syft.yaml

@@ -0,0 +1,7 @@
+select-catalogers:
+  - -go-module-binary-cataloger
+  - -github-action-workflow-usage-cataloger
+  - -github-actions-usage-cataloger
+
+exclude:
+  - "./.devenv"

.vscode/default.code-workspace

@@ -0,0 +1,12 @@
+{
+    "folders": [
+        {
+            "name": "root",
+            "path": "../"
+        },
+        {
+            "name": "typespec",
+            "path": "../api/spec"
+        }
+    ]
+}

.vscode/launch.json

@@ -0,0 +1,102 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Launch Server",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}/cmd/server",
+      "args": [
+        "--config",
+        "${workspaceFolder}/config.yaml",
+        "--stripe-disable-webhook-registration",
+      ]
+    },
+    {
+      "name": "Launch Sink-Worker",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}/cmd/sink-worker",
+      "args": [
+        "--config",
+        "${workspaceFolder}/config.yaml",
+        // Let's prevent port collision with server
+        "--telemetry-address",
+        ":10001",
+      ]
+    },
+    {
+      "name": "Launch Balance Worker",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}/cmd/balance-worker",
+      "args": [
+        "--config",
+        "${workspaceFolder}/config.yaml",
+        "--telemetry-address",
+        ":10002"
+      ]
+    },
+    {
+      "name": "Launch Notification Service",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}/cmd/notification-service",
+      "args": [
+        "--config",
+        "${workspaceFolder}/config.yaml",
+        "--telemetry-address",
+        ":10003"
+      ]
+    },
+    {
+      "name": "Launch recalculate entitlement snapshots",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}/cmd/jobs",
+      "args": [
+        "--config",
+        "${workspaceFolder}/config.yaml",
+        "entitlement",
+        "recalculate-balance-snapshots"
+      ]
+    },
+    {
+      "name": "Launch billing-worker Service",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}/cmd/billing-worker",
+      "args": [
+        "--config",
+        "${workspaceFolder}/config.yaml",
+        "--telemetry-address",
+        ":10004",
+        // force foreground billing advancement strategy, or billing-worker will not start (this way the config can be set to queued to validate that in local dev mode)
+        "--billing-advancement-strategy=foreground",
+      ]
+    },
+    {
+      "name": "Launch periodic jobs",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${workspaceFolder}/cmd/jobs",
+      "args": [
+        "--config",
+        "${workspaceFolder}/config.yaml",
+        "billing",
+        "subscriptionsync",
+        "list"
+      ]
+    },
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,32 @@
+{
+  "[helm]": {
+    "editor.formatOnSave": false
+  },
+  "go.testEnvVars": {
+    "TZ": "UTC",
+    "POSTGRES_HOST": "127.0.0.1",
+    "OPENMETER_ADDRESS": "http://127.0.0.1:38888",
+    // Useful when the schema is evolving during development (currently only supported
+    // by billing)
+    // "TEST_DISABLE_ATLAS": "true"
+  },
+  "gopls": {
+    "formatting.gofumpt": true
+  },
+  "go.lintTool": "golangci-lint",
+  "go.lintFlags": [
+    "--fast",
+    "--fix",
+    "-c",
+    ".golangci.yaml"
+  ],
+  "files.exclude": {
+    "**/node_modules": false
+  },
+  "typespec.tsp-server.path": "${workspaceFolder}/api/spec/node_modules/@typespec/compiler",
+  // dynamic forces confluent-kafka-go to build against local librdkafka
+  // wireinject is kept for gopls so it can analyse wire.go injection files
+  "go.buildTags": "wireinject,dynamic",
+  // Tests must NOT include wireinject — it causes wire stubs to run instead of wire_gen.go
+  "go.testTags": "dynamic"
+}

AGENTS.md

@@ -0,0 +1,323 @@
+# OpenMeter
+
+OpenMeter is a usage metering and billing platform for AI and DevTool companies, built in Go.
+
+## Quick Reference
+
+Use the `Makefile` for all common tasks. A `justfile` also exists but is seldom used.
+OpenMeter is a metering and billing platform with usage based pricing and access control.
+
+## Tips for working with the codebase
+
+If during your work anything confuses you or something isn't trivial for you, please augment AGENTS.md with your findings so next time it will be easier for you. AGENTS.md files are for you to edit and update as you go so you can interact with the codebase the most effectively.
+
+Development commands are run via `Makefile`, it contains all commonly used commands during development. A `justfile` is also present but seldom used. Use the Makefile commands for common tasks like running tests, generating code, linting, etc.
+The committed `.nvmrc` is the GitHub Actions source of truth for Node-based jobs on GitHub-hosted runners. Keep it aligned with the Nix `.#ci` shell's `node -v`; `flake.nix` refreshes it in `enterShell`, and CI validates the file against the Nix shell before running builds.
+
+## AGENTS.md maintenance
+
+- Treat this file as long-lived project guidance for all agents and contributors.
+- Treat AGENTS.md as the repo-local source of truth. Do not bypass coding style, workflow, testing, or documentation guidance in this file. If a requested change appears to conflict with AGENTS.md, ask the human developer/reviewer to confirm the exception before proceeding, and make the exception explicit in the handoff.
+- Prefer durable wording over time-based wording (avoid labels like "recent", "latest", "today").
+- Keep entries actionable and specific (what to do, where, and why), not conversational history.
+- Capture universal truths and cross-cutting coding conventions here when they become repeated practice or reviewer expectation. Do not leave them only in chat or pull request comments.
+- Capture subsystem-specific guidance in the closest applicable nested `AGENTS.md` when the guidance should always apply to a subtree, such as `api/spec/AGENTS.md` for TypeSpec and SDK guidance. Use skills for reusable workflows or domain procedures that agents opt into for a task. Skills must stay usable by both Claude and Codex: write them as plain repo guidance, keep `.agents/skills` as the source of truth, and avoid assistant-specific assumptions unless a workflow truly requires them.
+- When adding new guidance, fold it into the most relevant section and remove/merge stale or duplicate notes.
+
+## Testing
+
+| Task | Command |
+|------|---------|
+| Start dependencies | `make up` |
+| Stop dependencies | `make down` |
+| Run API server (hot reload) | `make server` |
+| Run all tests | `make test` (root module only; excludes `e2e/`, its own module) |
+| Run e2e tests | `make etoe` |
+| Generate all code | `make generate-all` |
+| Generate Go code only | `make generate` (runs `go generate ./...`) |
+| Generate API + SDKs | `make gen-api` |
+| Lint all | `make lint` |
+| Lint Go only | `make lint-go` |
+| Format code | `make fmt` |
+| Tidy modules | `make mod` (root + `collector` + `e2e`) |
+| Build all binaries | `make build` |
+
+## Architecture
+
+**Entry points:** `cmd/server`, `cmd/billing-worker`, `cmd/balance-worker`, `cmd/sink-worker`, `cmd/notification-service`, `cmd/jobs`
+
+Core business logic is in `openmeter/`, shared utilities in `pkg/`, API layer in `api/`.
+
+**Stack:** Go + PostgreSQL (Ent ORM) + Kafka + ClickHouse. API defined in TypeSpec, generated to OpenAPI.
+
+Domain packages under `openmeter/` follow a layered service/adapter pattern. See the `/service` skill for full details.
+
+`cmd/server/main.go` now migrates the database before creating the default namespace. Register namespace handlers before `initNamespace(...)` if they must provision the default namespace during startup.
+
+**Module layout:** the repo is three separate Go modules. The root module (`github.com/openmeterio/openmeter`) holds all production code (`cmd/`, `openmeter/`, `pkg/`, etc.). `api/v3/client` is the standalone, publishable v3 Go SDK module. `e2e/` is a third, never-published, test-only module that imports both — it pins itself to the working tree of each via `replace github.com/openmeterio/openmeter => ../` and `replace .../api/v3/client => ../api/v3/client`, so e2e always tests local code regardless of what's tagged. The root module must never `require` the SDK module: a `require` on an untagged nested module resolves to an unresolvable `v0.0.0` for anyone outside this repo (the `replace` directive that makes it resolve locally is invisible downstream), so any code that needs the SDK — today, only `e2e/` — has to live in its own module rather than the root one. Because of this, root `go build ./...` / `go test ./...` / `go vet ./...` no longer see `e2e/` at all; use `make etoe` (runs it against a live server) or `go test -C e2e ./...` / `go vet -C e2e ./...` (compiles it standalone, no server needed) instead. `make lint-go` and `make mod` already cover all three modules. For editor/gopls support across all three, run `go work init . ./api/v3/client ./e2e` locally — `go.work`/`go.work.sum` are gitignored and must never be committed.
+
+### Project Layout
+
+```
+cmd/                    # Service entrypoints
+openmeter/              # Core business logic (billing, customer, entitlement, meter, etc.)
+openmeter/ent/schema/   # Ent entity definitions (source of truth for DB schema)
+openmeter/ent/db/       # Generated ent code (DO NOT EDIT)
+api/                    # API specs, generated code, SDKs
+api/spec/               # TypeSpec API definitions (source of truth for API)
+pkg/                    # Shared utility packages
+tools/migrate/          # Migration tooling and SQL migration files
+e2e/                    # End-to-end tests
+deploy/                 # Helm charts
+docs/                   # Documentation and ADRs
+```
+
+## Code Generation
+
+All generated files have `// Code generated by X, DO NOT EDIT.` headers — never edit them manually:
+
+
+| Generated artifact | Source | Regenerate with |
+|---|---|---|
+| `api/openapi.yaml`, `api/openapi.cloud.yaml` | TypeSpec in `api/spec/` | `make gen-api` |
+| `api/client/javascript/`, `api/client/go/` | OpenAPI spec | `make gen-api` |
+| `api/v3/client/` (v3 Go SDK, standalone module) | TypeSpec in `api/spec/` via `@openmeter/typespec-go` | `make gen-api` |
+| `api/api.gen.go`, `api/v3/api.gen.go` | OpenAPI spec via oapi-codegen | `make gen-api` |
+| `api/client/go/client.gen.go` | OpenAPI spec | `make gen-api` |
+| `**/ent/db/` | Ent schema in `openmeter/ent/schema/` | `make generate` |
+| `**/wire_gen.go` | Wire providers in `**/wire.go` | `make generate` |
+| `**/convert.gen.go` | Goverter converter interfaces (`**/convert.go`) | `make generate` |
+| `billing/derived.gen.go` | Goderive annotations | `make generate` |
+| `tools/migrate/migrations/` | Ent schema diff | `atlas migrate --env local diff <name>` |
+
+**Workflow for changing the API:**
+
+1. Edit TypeSpec files in `api/spec/`
+2. Run `make gen-api` to regenerate OpenAPI spec and SDKs
+3. Run `make generate` to regenerate Go server/client code
+
+The TypeSpec JS client emitted from `api/spec/packages/aip` now lands in `api/spec/packages/aip-client-javascript/`. The emitter regenerates `src/`, `README.md`, and five conformance test files (`tests/client.spec.ts`, `tests/meters.spec.ts`, `tests/errors.spec.ts`, `tests/nesting.spec.ts`, `tests/internal.spec.ts`); every regenerated file carries a `Code generated by @openmeter/typespec-typescript. DO NOT EDIT.` header — treat files without that header as hand-written. `package.json` is **stable, hand-maintained, and committed** (the emitter's `writeOutput` only writes the paths it lists, so the manifest survives regeneration). The test suite is vitest + `@fetch-mock/vitest`; keep hand-written tests and helpers in `tests/` (never `src/`), and put test-runner dependencies/scripts in the `api/spec/package.json` workspace root rather than the client package manifest. Static publish metadata (`name`, `license`, `homepage`, `repository`) lives directly in the client `package.json`; only the per-release `version` is injected at publish time. Operations marked `x-internal` or `x-private` in the TypeSpec source are emitted but quarantined under `client.internal.<group>.<method>` (`src/sdk/internal.ts`, an `Internal` aggregate with `Internal<Group>` facade classes; internal ops share their group's `funcs/` and `models/operations/` modules, a group whose ops are all internal gets no public facade, and the `Internal` class is deliberately not re-exported from the package root — the name belongs to the Internal Server Error model). Removing an operation from the spec leaves stale generated files behind — the emitter never deletes outputs, so `git rm` them (and `rm` the gitignored `*.assert.ts` companions, which `git rm` cannot clean up on collaborators' checkouts).
+
+The emitted `api/spec/packages/aip-client-javascript/src/sdk/sdk.ts` exposes aggregated sub-client getters on the `OpenMeter` class (e.g. `events`, `meters`, `customers`, `entitlements`, `subscriptions`, `billing`, `features`, `plans`, `addons`, `planAddons`, `tax`, `defaults`). Access operations through those getters, e.g. `sdk.meters.list()`, `sdk.customers.create(...)`, `sdk.plans.create(...)`. These grouped-client methods throw `HTTPError` on failure; the same operations are also available as tree-shakeable standalone functions under `src/funcs/` that return a `Result` instead of throwing.
+
+**Workflow for changing Go types/DI:**
+
+1. Edit the source files (ent schema, wire.go, converter interfaces)
+2. Run `make generate` (or `go generate ./...`)
+
+## Database Migrations
+
+Uses [ent](https://entgo.io) for schema definition and [Atlas](https://atlasgo.io/) for migration generation. Migrations are in `tools/migrate/migrations/` using golang-migrate format.
+
+**Schema files:** `openmeter/ent/schema/*.go`
+
+**Workflow for schema changes:**
+
+1. Edit the ent schema in `openmeter/ent/schema/`
+2. Run `make generate` to regenerate ent code in `openmeter/ent/db/`
+3. Generate migration: `atlas migrate --env local diff <migration-name>`
+   - This creates timestamped `.up.sql` / `.down.sql` files in `tools/migrate/migrations/`
+   - Also updates `tools/migrate/migrations/atlas.sum`
+4. Versioned migrations run automatically on startup when `postgres.autoMigrate` is set to `migration`; runtime Ent migration is not supported
+
+**Ent view caveat:** in this repo's current Ent/Atlas setup, schemas declared with `ent.View` can generate query code under `openmeter/ent/db/`, but they do not appear in `openmeter/ent/db/migrate/schema.go` or the generated `migrate.Tables` list. If `atlas migrate --env local diff ...` reports no changes for a new view, verify whether the view exists in generated migration metadata before debugging Atlas; view DDL may need an explicit SQL migration until generator support is added.
+
+**Atlas config:** `atlas.hcl` — schema source is `ent://openmeter/ent/schema`, migrations dir is `file://tools/migrate/migrations`.
+
+**Local Postgres:** `postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable`
+
+Runtime Ent schema migration is not supported. `postgres.autoMigrate: ent` must fail validation; use `migration`, `migration-job`, or `false`. `openmeter-jobs migrate adopt-ent` contains a frozen compatibility bridge for databases created by Ent before migration baseline `20260709134422`; it stops at that baseline, after which `openmeter-jobs migrate` performs the normal target-version upgrade. Keep the frozen descriptors and reconciliation scripts under `tools/migrate/legacyent` independent from current Ent generation so later schema changes cannot alter the adoption baseline. Ent and Atlas can derive different names for equivalent indexes and constraints, so reconciliation must preserve the canonical Atlas names and `TestLegacyEntAdoptionSchemaParity` must continue comparing the adopted database with a from-scratch Atlas database.
+
+## Testing
+
+Tests require PostgreSQL running locally. Start it with `docker compose up -d postgres`.
+
+Keep domain test helpers under `openmeter/.../testutils` independent from `app/common`. Build test dependencies from the underlying package constructors (repos, adapters, services, `lockr`) instead of importing the application wiring layer, or unrelated wiring additions can create test-only import cycles.
+
+For usage-based billing lifecycle tests, prefer driving behavior through `charges.Service.Create`, `AdvanceCharges`, and `ApplyPatches` rather than calling lower-level charge adapters directly. To model late-arriving or newly visible usage, use `MockStreamingConnector` events with explicit `StoredAt` values (or `SetSimpleEvents`) so the test exercises the real stored-at cutoff logic in finalization.
+
+For OpenMeter Go tests that touch the database, explicitly set `POSTGRES_HOST=127.0.0.1`. Without it, many suites will skip during setup even if PostgreSQL is running and the repo environment is otherwise loaded correctly.
+
+Use the repo's Nix CI dev shell when `go`, `gofmt`, or other toolchain binaries are missing from the ambient shell. The CI and local-compatible invocation pattern is:
+
+```bash
+nix develop --impure .#ci -c <command>
+```
+
+Always invoke `nix develop` with the repo root as the working directory (use absolute paths in `<command>` instead of `cd`-ing first). The devenv `enterShell` writes CWD-relative state: run from a subdirectory it drops `.devenv/`, `.nvmrc`, and `.pre-commit-config.yaml` there (which then fail `prettier --check` in lint) and reinstalls the git pre-commit hook with that subdirectory's config path baked in, breaking later commits until a root-CWD `nix develop` run repairs it.
+
+Codex's default shell may not auto-load `.envrc`, so `direnv`-managed tools like `go` can be missing even when the repo is configured correctly. In that case, run commands through `nix develop --impure .#ci -c ...` explicitly instead of assuming the ambient shell reflects the flake environment. `direnv exec . <command>` is also a valid one-off fallback when `direnv` is installed and the repo has already been allowed.
+
+When invoking commands through Codex tools, prefer direct command execution. Do not wrap commands in `sh -lc`, `bash -lc`, or other helper shells when the command can be run directly. For environment variables, prefer `env KEY=value <command>` or `KEY=value <command>` over shell-wrapped forms. This keeps failures attributable to the actual toolchain/runtime being tested.
+
+In tests, prefer `t.Context()` when a `testing.T` or `testing.TB` is available instead of introducing `context.Background()`. This keeps cancellation and test-scoped lifecycle tied to the test harness.
+
+Prefer one consistent test harness style over mixed ad hoc structures. Use production-backed paths, such as rating-backed or service-backed fixtures, when the real path can express the scenario; keep hand-assembled fixtures for cases that cannot be produced realistically. If a behavior is a suite-wide rule, hardcode it into the shared harness instead of exposing it as per-test knobs.
+
+Avoid redundant test helpers and duplicate setup paths. Prefer parameterizing one helper over maintaining near-identical helpers, use literal helper names that state exactly what they do, and inline single-use helpers that only wrap setup, conversion, or assertions even when the test becomes longer. Add a test helper only when it is used by at least two tests in the same package or when the helper name captures non-obvious domain semantics that would otherwise be easy to miss. Clean up dead test helpers immediately after refactors.
+
+For service and lifecycle subtests, start each subtest body with concise intent comments when the scenario is non-trivial:
+
+```go
+// given:
+// - ...
+// when:
+// - ...
+// then:
+// - ...
+```
+
+When using `clock.FreezeTime(...)` in tests, immediately pair it with `defer clock.UnFreeze()` in the same scope so later assertions or subtests do not inherit frozen time accidentally.
+
+When asserting `alpacadecimal.Decimal` equality in tests, prefer `require.Equal(t, expectedFloat64, actual.InexactFloat64())` over boolean assertions like `require.True(t, expected.Equal(actual))` when precision requirements allow it. Prefer simple `float64(5)`-style literals over verbose decimal construction for expected values. Inline one-off expected balance structs at the assertion site; name expected balances only when reused or when the name carries useful phase semantics across subtests.
+
+After each meaningful test-related change, run focused `go vet` and focused `go test` for the touched package.
+
+Examples:
+
+```bash
+nix develop --impure .#ci -c gofmt -w openmeter/ledger/historical/entry.go
+nix develop --impure .#ci -c make lint-go
+nix develop --impure .#ci -c env POSTGRES_HOST=127.0.0.1 go test -tags=dynamic ./openmeter/ledger/historical/...
+```
+
+| Command | Description |
+|---------|-------------|
+| `make test` | Run all tests (parallel: `-p 128 -parallel 16`) |
+| `make test-nocache` | Run tests bypassing cache |
+| `make test-all` | Run tests including Svix/Redis dependencies |
+| `make test-go-sdk` | Build, vet, and test the v3 Go SDK module (`api/v3/client`) |
+| `make etoe` | Run e2e tests (requires docker compose dependencies) |
+
+**Running a single package directly:**
+
+```bash
+POSTGRES_HOST=127.0.0.1 go test -tags=dynamic -v ./openmeter/billing/...
+```
+
+Key flags: `-tags=dynamic` (required for confluent-kafka-go), `-p 128 -parallel 16` (used by Make). Set `POSTGRES_HOST=127.0.0.1` or tests requiring Postgres will be skipped. `e2e/` is its own module and its import graph never reaches confluent-kafka-go, so `-tags=dynamic` is not needed there — `go test -C e2e ./...` (or `TZ=UTC OPENMETER_ADDRESS=... go test -C e2e ./...`) is enough.
+
+See the `/test` skill for testing patterns, TestEnv setup, and examples.
+
+## Building
+
+```bash
+make build              # All binaries → build/
+make build-server       # Just the server
+```
+
+All builds use `GO_BUILD_FLAGS=-tags=dynamic`.
+
+## Configuration
+
+- Copy `config.example.yaml` to `config.yaml` (done automatically by Make targets)
+- Load the repository environment with `direnv`, or run commands with `direnv exec . <command>`, so project-specific environment variables and tool configuration are applied consistently
+- Key settings: `postgres.url`, `postgres.autoMigrate`, `billing`, `notification`, meter definitions
+- `credits.enabled` needs explicit guarding at multiple layers: ledger-backed customer credit handlers in `api/v3/server`, customer ledger hooks, and namespace/default-account provisioning are wired separately and must each stay disabled when credits are off.
+- When `credits.enabled` is `false`, `app/common` wires ledger account services/resolvers to noop implementations. Any ledger account backfill that must write real `ledger_accounts` / `ledger_customer_accounts` rows needs to construct concrete ledger account + resolver adapters directly instead of relying on the default DI outputs.
+- Make targets for running services will warn if `config.yaml` is outdated vs `config.example.yaml`
+
+## Coding Conventions
+
+See the `/service` skill for service/adapter patterns, constructors, input types, errors, transactions, hooks, logging, multi-tenancy, and DI wiring. See the `/api` skill for HTTP handler patterns and ValidationIssue. See the `/ent` skill for Ent ORM patterns and Postgres type gotchas. See the `/ledger` skill for ledger package architecture, wiring, and testing. See the `/subscription` skill for subscription domain model, sync algorithm, patch system, workflow layer, and addon sub-system. See the `/notification` skill for notification event pipeline, Kafka consumers, Svix webhook delivery, reconciliation loop, and payload versioning.
+
+For TypeSpec-specific coding constraints, update `api/spec/AGENTS.md` instead of adding them here.
+
+### Documentation Constraints
+
+- When adding comments or docstrings, document intent and domain constraints that are only available from human author context, not facts a reader can infer by reading the codebase. Avoid comments that merely translate obvious conditions, such as saying that a branch runs when `servicePeriod > 0`. A good comment should be understandable without the author's chat context and should explain why the code deliberately includes or excludes a case. For fallback or guard comments, name the concrete input shape or lifecycle state, the invariant being protected, the chosen behavior, and what would go wrong if the guard or fallback were removed. Avoid vague phrases like "can still arrive" or "as needed".
+- Add a docstring to domain helpers when the name compresses important business semantics that are easy to misread at call sites. Explain the observable business contract and why excluded cases are excluded, not the implementation mechanics.
+- When refactoring or reverting code, preserve existing explanatory comments by default. Remove or rewrite a comment only when the code change makes it false, stale, or misleading.
+
+### Go Style Constraints
+
+- For Go string enum constants, name values as `<Type><Value>` so the constant carries its enum type at the use site, for example `InvoiceStatusDraft` instead of `Draft`.
+- Do not extract helper functions only to hide a couple of simple operations or short guard checks. If the helper would only wrap 2-4 lines and its name does not add meaningful domain or business intent, keep the code inline even when there is some duplication. Readers can inspect the function body to see what the code does; prefer function names that explain the domain reason for the call over names that merely restate the implementation steps. When you encounter a leftover pass-through wrapper that only calls another function without adding behavior, remove it and call the underlying function directly, even if it is outside the immediate change area.
+- Do not hide non-trivial branching or domain translation inside local inline functions. If a closure performs type switching, validation, persistence mapping, or meaningful domain conversion, make it a named helper near the code that uses it so it is discoverable, testable, and grep-friendly. Reserve inline closures for tiny callbacks where the surrounding API requires a function literal and the logic is obvious at the call site.
+- For `Validate() error` methods, prefer collecting all validation issues into `var errs []error` and returning `models.NewNillableGenericValidationError(errors.Join(errs...))` instead of returning on the first invalid field. Preserve field context with wrapped errors like `fmt.Errorf("field: %w", err)` and use plain `errors.New(...)` for simple local checks.
+- Do not introduce `context.Background()` or `context.TODO()` to sidestep missing context propagation in application code. Either propagate the caller's context through the full call path, or remove the unused `context.Context` parameter from the API if the operation is purely local and does not need cancellation, deadlines, or request-scoped values.
+- Never use `panic` in non-test code paths. If a new failure mode is possible, change the function signature to return an error and propagate it explicitly.
+- In production constructors and initialization, do not use `slog.Default()` as a fallback dependency. Require a `*slog.Logger` in config/provider inputs and inject it explicitly.
+- Prefer standard library `slices` and `maps` helpers for common collection operations, and use `github.com/samber/lo` when it makes pointer literals or collection transformations clearer than local wrappers or hand-written loops. See the `/samber-lo` skill for common OpenMeter use cases and caveats. Do not add local wrappers such as `ptr`, `loPtr`, `must`, or `loMust` when standard helpers or `lo` already cover the need.
+- Use repo helper packages when they capture a common pattern better than ad hoc closures. For example, use `pkg/slicesx` for existing slice helpers (but prefer `samber/lo` and `slices` system packages if they fit), and use `pkg/syncx.OnceValues` for lazy context-aware database lookups that may be needed by multiple callbacks but should execute at most once.
+- Keep helper functions honest and narrow. If a production helper is only called once and is just a short guard or a few straightforward lines, inline it unless the name carries meaningful domain semantics. Do not add helpers for trivial single-use struct literals, do not hide aggregate mutation inside construction helpers, and return the domain value a helper actually builds rather than a broader wrapper needed by one caller.
+- For files and functions that convert between domain, API, and DB representations, use the `/go-types-conversion` skill. In prose, prefer `map` / `mapped` terminology for domain representation translation and avoid `project` / `projected` for that meaning; function names must still follow the skill's `FromAPI...`, `ToAPI...`, `FromDB...`, and `ToDB...` conventions.
+
+### Generation And Dependency Constraints
+
+- When `make generate` or `atlas migrate --env local diff ...` adds incidental `go.sum` entries, such as `tablewriter`, drop those `go.sum` changes unless the task explicitly requires a dependency change.
+
+## Key Dependencies
+
+| Category | Libraries |
+|----------|-----------|
+| DB | PostgreSQL (Ent ORM, Atlas migrations, pgx driver) |
+| Analytics | ClickHouse |
+| Events | Kafka (confluent-kafka-go) + Watermill |
+| HTTP | Chi router + oapi-codegen |
+| Invoicing | GOBL (invoice format) |
+| Webhooks | Svix |
+| Observability | OpenTelemetry |
+| Config | Viper + Cobra |
+| Utilities | samber/lo |
+
+## CodeGraph
+
+CodeGraph builds a semantic knowledge graph of the codebase (~1,800 Go files, ~36k symbols) for faster, smarter code exploration. The index lives in `.codegraph/codegraph.db` (gitignored). Generated files (`ent/db/`, `*_gen.go`, `wire_gen.go`, `*.gen.go`) are excluded.
+
+### If `.codegraph/` exists
+
+**Default to CodeGraph, not Grep/Glob/find.** CodeGraph understands symbols, call relationships, and file structure — those tools return string matches. On a ~1,800-file Go codebase the symbol-aware answer is almost always what you wanted. Fall back to Grep/Glob **only** when CodeGraph returns no results or the query is inherently textual (string literals, comments, log messages, SQL, YAML keys).
+
+**Never call `codegraph_explore` or `codegraph_context` in the main session.** These tools return large source code blocks that fill up main-session context fast. Instead, spawn an Explore agent for any exploration question (e.g., "how does billing sync work?", "where is entitlement reset implemented?").
+
+When spawning Explore agents, include this instruction in the prompt:
+
+> This project has CodeGraph initialized (.codegraph/ exists). Use `codegraph_explore` as your PRIMARY exploration tool — it returns full source code sections from all relevant files in one call.
+>
+> **Rules:**
+> 1. Follow the explore call budget in the `codegraph_explore` tool description — it scales automatically based on project size.
+> 2. Do NOT re-read files that `codegraph_explore` already returned source code for. The source sections are complete and authoritative.
+> 3. Only fall back to Grep/Glob/Read for files listed under "Additional relevant files" if you need more detail, or if CodeGraph returned no results.
+
+**The main session should use these lightweight tools directly** for targeted lookups before making edits:
+
+| Tool | Use for | Example |
+|------|---------|---------|
+| `codegraph_search` | Find symbols by name | `query: "BillingService"` |
+| `codegraph_callers` | Who calls this function? | Before renaming or changing a signature |
+| `codegraph_callees` | What does this function call? | Understanding a function's dependencies |
+| `codegraph_impact` | Blast radius of a change | Before refactoring a shared type |
+| `codegraph_node` | Single symbol details | Quick check on a struct or interface |
+| `codegraph_files` | Project file tree | Faster than Glob for directory overviews |
+| `codegraph_status` | Index health check | Verify the index is up to date |
+
+### Choosing CodeGraph vs Grep/Glob
+
+| Task | Prefer | Reason |
+|------|--------|--------|
+| "Where is `BillingService` defined?" | `codegraph_search` | Symbol lookup with location + signature |
+| "Who calls `ListCustomers`?" | `codegraph_callers` | Call-graph edges, not text matches |
+| "What does `Reconcile` call?" | `codegraph_callees` | Dependencies of a function |
+| "Blast radius of changing this type?" | `codegraph_impact` | Transitive reverse-deps |
+| "Show the `Filter` interface fields" | `codegraph_node` | Single-symbol detail without reading whole file |
+| "List files under `api/v3/filters/`" | `codegraph_files` | Indexed tree; no disk walk |
+| Find a string literal / log message / SQL fragment | `Grep` | Not a symbol |
+| Find files by glob pattern (`**/*.tsp`) | `Glob` | CodeGraph indexes Go; non-Go globs go through Glob |
+| Navigate a specific known path | `Read` | Direct reads are always fine |
+| Running `find` on the shell | Don't | Use `codegraph_files` or `Glob` |
+| Running `grep`/`rg` on the shell | Don't | Use `Grep` (or `codegraph_search` for symbols) |
+
+Rule of thumb: **if the target is a Go identifier, start with CodeGraph. If it's a string, start with Grep.** Never shell out to `grep`, `rg`, or `find` — the dedicated tools (`Grep`, `Glob`, `codegraph_*`) give better output and permission handling.
+
+### Keeping the index fresh
+
+At the start of work, refresh CodeGraph before exploring Go code. If `.codegraph/` exists, run `codegraph sync`; if it does not exist, run `codegraph init -i` without asking first. Run `codegraph index` for a full rebuild if the index seems stale or after branch switches.
+
+### If `.codegraph/` does NOT exist
+
+Initialize it with `codegraph init -i` before doing code exploration. It indexes the Go codebase quickly and keeps symbol-aware lookup available.
+
+## Skills
+
+Skills are created inside [.agents/skills](.agents/skills/) by default and then symlinked to [.claude/skills](.claude/skills). Make sure you always treat `.agents/skills` as the source of truth. Keep skill guidance compatible with both Claude and Codex; avoid instructions that assume only one agent runtime unless the skill is explicitly about that runtime.

Agent.md

@@ -0,0 +1,148 @@
+# Hugging Face Space Deployment Agent Guide
+
+This file outlines the deployment configuration, API exposure, and deployment workflow for OpenMeter on Hugging Face Spaces.
+
+## 1. Deployment Configuration
+
+### Target Space
+- **Profile:** `Leon4gr45`  
+- **Space:** `openmeter`  
+- **Full Identifier:** `Leon4gr45/openmeter`  
+- **Frontend Port:** `7860` (mandatory for all Hugging Face Spaces)
+
+### Deployment Method
+Choose the correct SDK based on the app type based on the codebase language:
+- **Docker SDK** is used for OpenMeter (as a Go application).
+
+### HF Token
+- The environment variable `HF_TOKEN` must be set to your Hugging Face Space token at execution time (never hardcode the token).
+- All monitoring, upload, and log-streaming commands rely on this token.
+
+### Required Files
+- `Dockerfile` (packaged to run with the mock server enabled for space readiness)
+- `README.md` with Hugging Face YAML frontmatter specifying:
+  ```yaml
+  ---
+  title: Openmeter
+  sdk: docker
+  app_port: 7860
+  ---
+  ```
+- `.hfignore` to exclude unnecessary files.
+- `Agent.md` (this file, committed before deployment).
+
+---
+
+## 2. API Exposure and Documentation
+
+### Mandatory Endpoints
+Every deployment **must** expose:
+
+- **`/health`**  
+  - Returns HTTP 200 `OK` (plain text or JSON) when the app is ready.  
+  - Required for Hugging Face to transition the Space from *starting* → *running*.
+
+- **`/api-docs`**  
+  - Documents **all** available API endpoints.  
+  - Must be reachable at:  
+    `https://Leon4gr45-openmeter.hf.space/api-docs`
+
+---
+
+### Functional Endpoints
+
+The mock server exposed in this space implements the following critical OpenMeter functional endpoints (all of which are documented in `/api-docs` via `/api/swagger.json`):
+
+#### 1. Ingest Events
+- **Method:** POST
+- **Path:** `/api/v1/events`
+- **Purpose:** Ingest event data in CloudEvents format.
+- **Request Example:**
+  ```json
+  {
+    "specversion": "1.0",
+    "type": "request",
+    "id": "00001",
+    "time": "2026-07-07T00:00:00.001Z",
+    "source": "my-service",
+    "subject": "customer-1",
+    "data": { "method": "GET", "route": "/api/hello" }
+  }
+  ```
+- **Response Example:**
+  ```json
+  {
+    "status": "accepted"
+  }
+  ```
+
+#### 2. List Meters
+- **Method:** GET
+- **Path:** `/api/v1/meters`
+- **Purpose:** List all configured usage meters.
+- **Request:** (None)
+- **Response Example:**
+  ```json
+  [
+    {
+      "id": "api_requests_total",
+      "slug": "api_requests_total",
+      "description": "API Requests",
+      "eventType": "request",
+      "aggregation": "COUNT"
+    },
+    {
+      "id": "tokens_total",
+      "slug": "tokens_total",
+      "description": "AI Token Usage",
+      "eventType": "prompt",
+      "aggregation": "SUM"
+    }
+  ]
+  ```
+
+#### 3. Query Meter Usage
+- **Method:** GET
+- **Path:** `/api/v1/meters/{meterIdOrSlug}/query`
+- **Purpose:** Query usage data for a specific meter.
+- **Request Parameters:** `windowSize=HOUR`
+- **Response Example:**
+  ```json
+  {
+    "data": [
+      {
+        "value": 150,
+        "windowStart": "2026-07-07T00:00:00Z",
+        "windowEnd": "2026-07-07T01:00:00Z"
+      }
+    ]
+  }
+  ```
+
+---
+
+## 3. Deployment Workflow
+
+Precondition: Check that the space is empty of files and delete any which are still in there and not belonging to the project to be uploaded.
+
+### Standard Deployment Command
+After any code change, run:
+
+```bash
+HF_TOKEN=<HF_TOKEN_VALUE> hf upload Leon4gr45/openmeter . . --repo-type=space
+```
+
+### Scan build and run logs
+Get build logs (SSE):
+```bash
+curl -N -H "Authorization: Bearer <HF_TOKEN_VALUE>" "https://huggingface.co/api/spaces/Leon4gr45/openmeter/logs/build"
+```
+
+Get run logs (SSE) once the build logs succeed:
+```bash
+curl -N -H "Authorization: Bearer <HF_TOKEN_VALUE>" "https://huggingface.co/api/spaces/Leon4gr45/openmeter/logs/run"
+```
+
+Cycle monitoring and deployment:
+- Wait up to 300 seconds to see if the deployment has been successful.
+- If not, check logs for errors, fix the issues in the codebase, redeploy, and monitor again in a cycle until the space is running and reacts successfully to API endpoints.

CLAUDE.md

@@ -0,0 +1,3 @@
+# OpenMeter Development Guide
+
+See consolidated agents instructions in @AGENTS.md

CODE_OF_CONDUCT.md

@@ -0,0 +1,68 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment,
+we as contributors and maintainers pledge to make participation in our project
+and our community a harassment-free experience for everyone, regardless of age,
+body size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior
+and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit,
+or reject comments, commits, code, wiki edits, issues,
+and other contributions that are not aligned to this Code of Conduct,
+or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces,
+and it also applies when an individual is representing the project or its community in public spaces.
+Examples of representing a project or community include using an official project e-mail address,
+posting via an official social media account, or acting as an appointed representative at an online or offline event.
+Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [conduct@openmeter.io][conduct-email].
+All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
+The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary
+or permanent repercussions as determined by other members of the project's leadership.
+
+[conduct-email]: mailto:conduct@openmeter.io
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for your interest in contributing to OpenMeter!
+
+Here are a few general guidelines on contributing and reporting bugs that we ask you to review.
+Following these guidelines helps to communicate that you respect the time of the contributors managing and developing this open source project.
+In return, they should reciprocate that respect in addressing your issue, assessing changes, and helping you finalize your pull requests.
+In that spirit of mutual respect, we endeavor to review incoming issues and pull requests within 10 days,
+and will close any lingering issues or pull requests after 60 days of inactivity.
+
+Please note that all of your interactions in the project are subject to our [Code of Conduct](/CODE_OF_CONDUCT.md).
+This includes creation of issues or pull requests, commenting on issues or pull requests,
+and extends to all interactions in any real-time space e.g., Slack, Discord, etc.
+
+## Reporting issues
+
+Before reporting a new issue, please ensure that the issue was not already reported or fixed by searching through our issue tracker.
+
+When creating a new issue, please be sure to include a **title and clear description**, as much relevant information as possible, and, if possible, a test case.
+
+**If you discover a security bug, please do not report it through GitHub issues. Instead, please see security procedures in [SECURITY.md](/SECURITY.md).**
+
+## Sending pull requests
+
+Before sending a new pull request, take a look at existing pull requests and issues to see if the proposed change or fix has been discussed in the past,
+or if the change was already implemented but not yet released.
+
+We expect new pull requests to include tests for any affected behavior, and, as we follow semantic versioning,
+we may reserve breaking changes until the next major version release.
+
+### Ensuring All Requested Reviewers Approve
+
+By default, pull requests can often be merged once the minimum number of required approvals (e.g., from CODEOWNERS or branch protection rules) is met. However, sometimes you might explicitly request reviews from specific individuals because their input is crucial for that particular PR.
+
+To ensure that *all* individuals you've specifically requested using the GitHub "Reviewers" UI must approve before merging, follow these steps:
+
+1.  **Request Reviews:** Use the standard GitHub interface on the pull request page to request reviews from the necessary individuals.
+2.  **Add Label:** Add the label `require-all-reviewers` to the pull request.
+
+When this label is present, an automated check named "Review Gatekeeper" will run. This check will only pass if **every single user** listed under the "Reviewers" section has submitted an **approving** review. This check is required for merging, preventing merges until all explicitly requested reviewers are satisfied.
+
+If the label is removed, the "Review Gatekeeper" check will be skipped.
+
+## Other ways to contribute
+
+We welcome anyone that wants to contribute to triage and reply to open issues to help troubleshoot and fix existing bugs.
+Here is what you can do:
+
+- Help ensure that existing issues follows the recommendations from the _[Reporting Issues](#reporting-issues)_ section,
+  providing feedback to the issue's author on what might be missing.
+- Review and update the existing content of our [documentation](https://openmeter.io) with up-to-date instructions and code samples.
+- Review existing pull requests, and testing patches against real existing applications.
+- Write a test, or add a missing test case to an existing test.

Dockerfile

@@ -0,0 +1,98 @@
+FROM --platform=$BUILDPLATFORM tonistiigi/xx:1.9.0@sha256:c64defb9ed5a91eacb37f96ccc3d4cd72521c4bd18d5442905b95e2226b0e707 AS xx
+
+FROM --platform=$BUILDPLATFORM golang:1.26.4-alpine3.23@sha256:18b460dd17542c2ba43299a633cf6ebfc1115101509531471d7cfce1019af083 AS builder
+
+COPY --link --from=xx / /
+
+RUN xx-apk add --update --no-cache ca-certificates make git curl clang lld
+
+ARG TARGETPLATFORM
+
+RUN xx-apk --update --no-cache add musl-dev gcc
+
+WORKDIR /src
+
+ARG GOPROXY
+
+ENV CGO_ENABLED=1
+
+ENV GOCACHE=/go/cache
+ENV GOMODCACHE=/go/pkg/mod
+
+COPY --link go.mod go.sum ./
+
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/go/cache \
+    xx-go mod download -x
+
+ARG VERSION
+
+COPY --link . .
+
+RUN chmod +x entrypoint.sh
+
+# See https://github.com/confluentinc/confluent-kafka-go#librdkafka
+# See https://github.com/confluentinc/confluent-kafka-go#static-builds-on-linux
+# Build server binary (default)
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/go/cache \
+    xx-go build -ldflags "-linkmode external -extldflags \"-static\" -X main.version=${VERSION}" -tags musl -o /usr/local/bin/openmeter ./cmd/server
+
+RUN xx-verify /usr/local/bin/openmeter
+
+# Build sink-worker binary
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/go/cache \
+    xx-go build -ldflags "-linkmode external -extldflags \"-static\" -X main.version=${VERSION}" -tags musl -o /usr/local/bin/openmeter-sink-worker ./cmd/sink-worker
+
+RUN xx-verify /usr/local/bin/openmeter-sink-worker
+
+# Build balance-worker binary
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/go/cache \
+    xx-go build -ldflags "-linkmode external -extldflags \"-static\" -X main.version=${VERSION}" -tags musl -o /usr/local/bin/openmeter-balance-worker ./cmd/balance-worker
+
+RUN xx-verify /usr/local/bin/openmeter-balance-worker
+
+# Build notification-service binary
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/go/cache \
+    xx-go build -ldflags "-linkmode external -extldflags \"-static\" -X main.version=${VERSION}" -tags musl -o /usr/local/bin/openmeter-notification-service ./cmd/notification-service
+
+RUN xx-verify /usr/local/bin/openmeter-notification-service
+
+# Build billing-worker binary
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/go/cache \
+    xx-go build -ldflags "-linkmode external -extldflags \"-static\" -X main.version=${VERSION}" -tags musl -o /usr/local/bin/openmeter-billing-worker ./cmd/billing-worker
+
+RUN xx-verify /usr/local/bin/openmeter-billing-worker
+
+# Build periodic jobs binary
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/go/cache \
+    xx-go build -ldflags "-linkmode external -extldflags \"-static\" -X main.version=${VERSION}" -tags musl -o /usr/local/bin/openmeter-jobs ./cmd/jobs
+
+RUN xx-verify /usr/local/bin/openmeter-jobs
+
+FROM alpine:3.24.1@sha256:28bd5fe8b56d1bd048e5babf5b10710ebe0bae67db86916198a6eec434943f8b
+
+ENV MOCK_SERVER=true
+ENV PORT=7860
+
+RUN apk add --update --no-cache ca-certificates tzdata bash
+
+SHELL ["/bin/bash", "-c"]
+
+COPY --link --from=builder /usr/local/bin/openmeter /usr/local/bin/
+COPY --link --from=builder /usr/local/bin/openmeter-sink-worker /usr/local/bin/
+COPY --link --from=builder /usr/local/bin/openmeter-balance-worker /usr/local/bin/
+COPY --link --from=builder /usr/local/bin/openmeter-notification-service /usr/local/bin/
+COPY --link --from=builder /usr/local/bin/openmeter-billing-worker /usr/local/bin/
+COPY --link --from=builder /usr/local/bin/openmeter-jobs /usr/local/bin/
+COPY --link --from=builder /src/go.* /usr/local/src/openmeter/
+COPY --link --from=builder /src/entrypoint.sh /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
+
+CMD openmeter

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Makefile

@@ -0,0 +1,356 @@
+# A Self-Documenting Makefile: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+
+ROOT_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+
+# Docker-local svix secret, only used for testing
+SVIX_JWT_SECRET = DUMMY_JWT_SECRET
+
+# dynamic forces confluent-kafka-go to build against local librdkafka
+GO_BUILD_FLAGS = -tags=dynamic
+GO_TEST_PACKAGE_PARALLELISM ?= 128
+GO_TEST_FLAGS = -p ${GO_TEST_PACKAGE_PARALLELISM} -parallel 16 ${GO_BUILD_FLAGS}
+GOTESTSUM_FLAGS ?= --format pkgname-and-test-fails --hide-summary=skipped
+GO_LINT_PATH ?= ./...
+
+.PHONY: up
+up: ## Start the dependencies via docker compose. `export COMPOSE_PROFILES=dev,redis,...`
+	$(call print-target)
+	docker compose up -d
+
+.PHONY: down
+down: ## Stop the dependencies via docker compose
+	$(call print-target)
+	docker compose down --remove-orphans --volumes
+
+.PHONY: patch-oapi-templates
+patch-oapi-templates: ## Patch oapi-codegen chi-middleware template with custom filter parsing
+	$(call print-target)
+	@go mod download github.com/oapi-codegen/oapi-codegen/v2
+	@OAPI_MOD_DIR=$$(go list -m -f '{{.Dir}}' github.com/oapi-codegen/oapi-codegen/v2) && \
+		if [ -z "$$OAPI_MOD_DIR" ]; then echo "error: could not locate oapi-codegen/v2 module dir"; exit 1; fi && \
+		cp "$$OAPI_MOD_DIR/pkg/codegen/templates/chi/chi-middleware.tmpl" api/v3/templates/chi-middleware.tmpl && \
+		chmod u+w api/v3/templates/chi-middleware.tmpl && \
+		patch -p1 -d api/v3/templates < api/v3/templates/chi-middleware.tmpl.patch
+
+.PHONY: update-openapi
+update-openapi: patch-oapi-templates ## Update OpenAPI spec
+	$(call print-target)
+	$(MAKE) -C api/spec generate
+	go generate ./api/...
+
+.PHONY: generate-javascript-sdk
+generate-javascript-sdk: ## Generate JavaScript SDK
+	$(call print-target)
+	$(MAKE) -C api/client/javascript generate
+
+.PHONY: gen-api
+gen-api: update-openapi generate-javascript-sdk ## Generate API and SDKs
+	$(call print-target)
+
+.PHONY: generate-all
+generate-all: update-openapi generate-javascript-sdk ## Execute all code generators
+	$(call print-target)
+	go generate ./...
+
+.PHONY: migrate-check
+migrate-check: migrate-check-schema migrate-check-diff migrate-check-lint migrate-check-validate ## Validate migrations
+
+.PHONY: migrate-check-schema
+migrate-check-schema: ## Ensure ent schema is in sync with generated code
+	$(call print-target)
+	go generate -x ./openmeter/ent/...
+	@if ! git diff --quiet -- openmeter/ent || [ -n "$$(git ls-files --others --exclude-standard -- openmeter/ent)" ]; then \
+		git --no-pager diff -- openmeter/ent; \
+		git ls-files --others --exclude-standard -- openmeter/ent; \
+		echo "!!! schema is not in sync with generated code — run 'go generate ./openmeter/ent/...' and commit the changes !!!"; \
+		exit 1; \
+	fi
+
+.PHONY: migrate-check-diff
+migrate-check-diff: ## Ensure migrations are in sync with schema (runs atlas migrate diff against a clean target)
+	$(call print-target)
+	atlas migrate --env local diff migrate-check >/dev/null
+	@if ! git diff --quiet -- tools/migrate/migrations || [ -n "$$(git ls-files --others --exclude-standard -- tools/migrate/migrations)" ]; then \
+		git --no-pager diff -- tools/migrate/migrations; \
+		git ls-files --others --exclude-standard -- tools/migrate/migrations; \
+		echo "!!! migrations are not in sync with schema — run 'atlas migrate --env local diff <name>' and commit the generated files !!!"; \
+		exit 1; \
+	fi
+
+.PHONY: migrate-check-lint
+migrate-check-lint: ## Lint the last 10 migrations
+	$(call print-target)
+	atlas migrate --env local lint --latest 10
+
+.PHONY: migrate-check-validate
+migrate-check-validate: ## Validate migration checksums
+	$(call print-target)
+	atlas migrate --env local validate
+
+.PHONY: generate-sqlc-testdata
+generate-sqlc-testdata: ## Generate SQLC testdata for a specific version (make generate-sqlc-testdata VERSION=20240826120919)
+	$(call print-target)
+	@if [ -z "$(VERSION)" ]; then echo "Usage: make generate-sqlc-testdata VERSION=<migration_version>"; exit 1; fi
+	VERSION=$(VERSION) ./tools/migrate/generate-sqlc-testdata.sh
+
+.PHONY: generate
+generate: patch-oapi-templates ## Generate code
+	$(call print-target)
+	go generate ./...
+
+.PHONY: generate-view-sql
+generate-view-sql: ## Generate SQL for ent.View schemas
+	$(call print-target)
+	go run ./tools/migrate/cmd/viewgen
+
+.PHONY: build-dir
+build-dir:
+	@mkdir -p build
+
+.PHONY: build
+build: build-server build-sink-worker build-benthos-collector build-balance-worker build-billing-worker build-notification-service build-jobs ## Build all binaries
+
+COLLECTOR_DIR := $(ROOT_DIR)/collector
+COLLECTOR_RELEASE_OUTPUT_DIR := $(ROOT_DIR)/build/release/benthos-collector_$(GOOS)_$(GOARCH)
+
+collector-release-output-dir:
+	$(if $(GOOS),,$(error GOOS is not set))
+	$(if $(GOARCH),,$(error GOARCH is not set))
+	@mkdir -p $(COLLECTOR_RELEASE_OUTPUT_DIR)
+
+# Cross-compile the benthos-collector binary for release archives.
+# Usage: make build-benthos-collector-release GOOS=linux GOARCH=amd64 VERSION=v1.2.3
+#   Produces build/release/benthos-collector_<GOOS>_<GOARCH>/benthos (+ README.md, LICENSE)
+.PHONY: build-benthos-collector-release
+build-benthos-collector-release: | collector-release-output-dir ## Cross-compile benthos-collector for release (set GOOS/GOARCH/VERSION)
+	$(call print-target)
+	$(if $(GOOS),,$(error GOOS is not set))
+	$(if $(GOARCH),,$(error GOARCH is not set))
+	@rm -rf "$(COLLECTOR_RELEASE_OUTPUT_DIR)"/* && \
+		CGO_ENABLED=0 GOOS=$(GOOS) GOARCH=$(GOARCH) \
+			go build -C $(COLLECTOR_DIR) -trimpath \
+			-ldflags "-s -w -X main.version=$(or $(VERSION),unknown)" \
+			-o "$(COLLECTOR_RELEASE_OUTPUT_DIR)/benthos" ./cmd && \
+		cp README.md LICENSE "$(COLLECTOR_RELEASE_OUTPUT_DIR)/"
+
+COLLECTOR_RELEASE_NAME := benthos-collector_$(GOOS)_$(GOARCH)
+
+# Produces build/release/benthos-collector_<GOOS>_<GOARCH>.tar.gz from the directory above.
+.PHONY: archive-benthos-collector-release
+archive-benthos-collector-release: ## Archive the cross-compiled benthos-collector (set GOOS/GOARCH)
+	$(call print-target)
+	$(if $(GOOS),,$(error GOOS is not set))
+	$(if $(GOARCH),,$(error GOARCH is not set))
+	@tar -C build/release -czf "build/release/$(COLLECTOR_RELEASE_NAME).tar.gz" "$(COLLECTOR_RELEASE_NAME)"
+
+.PHONY: build-server
+build-server: | build-dir ## Build server binary
+	$(call print-target)
+	go build -o build/server ${GO_BUILD_FLAGS} ./cmd/server
+
+.PHONY: build-sink-worker
+build-sink-worker: | build-dir ## Build sink-worker binary
+	$(call print-target)
+	go build -o build/sink-worker ${GO_BUILD_FLAGS} ./cmd/sink-worker
+
+.PHONY: build-benthos-collector
+build-benthos-collector: | build-dir ## Build benthos collector binary
+	$(call print-target)
+	go build -C $(COLLECTOR_DIR) -o ../build/benthos-collector ${GO_BUILD_FLAGS} ./cmd
+
+.PHONY: build-balance-worker
+build-balance-worker: | build-dir ## Build balance-worker binary
+	$(call print-target)
+	go build -o build/balance-worker ${GO_BUILD_FLAGS} ./cmd/balance-worker
+
+.PHONY: build-billing-worker
+build-billing-worker: | build-dir ## Build billing-worker binary
+	$(call print-target)
+	go build -o build/billing-worker ${GO_BUILD_FLAGS} ./cmd/billing-worker
+
+.PHONY: build-notification-service
+build-notification-service: | build-dir ## Build notification-service binary
+	$(call print-target)
+	go build -o build/notification-service ${GO_BUILD_FLAGS} ./cmd/notification-service
+
+.PHONY: build-jobs
+build-jobs: | build-dir ## Build jobs binary
+	$(call print-target)
+	go build -o build/jobs ${GO_BUILD_FLAGS} ./cmd/jobs
+
+config.yaml:
+	cp config.example.yaml config.yaml
+
+.PHONY: server
+server: ## Run sink-worker
+	@ if [ config.yaml -ot config.example.yaml ]; then diff -u config.yaml config.example.yaml || (echo "!!! The configuration example changed. Please update your config.yaml file accordingly (or at least touch it). !!!" && false); fi
+	$(call print-target)
+	air -c ./cmd/server/.air.toml
+
+.PHONY: sink-worker
+sink-worker: ## Run sink-worker
+	@ if [ config.yaml -ot config.example.yaml ]; then diff -u config.yaml config.example.yaml || (echo "!!! The configuration example changed. Please update your config.yaml file accordingly (or at least touch it). !!!" && false); fi
+	$(call print-target)
+	air -c ./cmd/sink-worker/.air.toml
+
+.PHONY: balance-worker
+balance-worker: ## Run balance-worker
+	@ if [ config.yaml -ot config.example.yaml ]; then diff -u config.yaml config.example.yaml || (echo "!!! The configuration example changed. Please update your config.yaml file accordingly (or at least touch it). !!!" && false); fi
+	$(call print-target)
+	air -c ./cmd/balance-worker/.air.toml
+
+.PHONY: billing-worker
+billing-worker: ## Run billing-worker
+	@ if [ config.yaml -ot config.example.yaml ]; then diff -u config.yaml config.example.yaml || (echo "!!! The configuration example changed. Please update your config.yaml file accordingly (or at least touch it). !!!" && false); fi
+	$(call print-target)
+	air -c ./cmd/billing-worker/.air.toml
+
+.PHONY: notification-service
+notification-service: ## Run notification-service
+	@ if [ config.yaml -ot config.example.yaml ]; then diff -u config.yaml config.example.yaml || (echo "!!! The configuration example changed. Please update your config.yaml file accordingly (or at least touch it). !!!" && false); fi
+	$(call print-target)
+	air -c ./cmd/notification-service/.air.toml
+
+.PHONY: llm-cost-sync
+llm-cost-sync: ## Sync LLM cost prices from external sources
+	$(call print-target)
+	go run ./cmd/jobs llm-cost sync
+
+.PHONY: etoe
+etoe: ## Run e2e tests
+	$(call print-target)
+	$(MAKE) -C e2e test-local
+
+.PHONY: etoe-slow
+etoe-slow: ## Run e2e tests with slow tests enabled
+	$(call print-target)
+	export RUN_SLOW_TESTS=1
+	$(MAKE) -C e2e test-local
+
+
+.PHONY: test
+test: ## Run tests
+	$(call print-target)
+	PGPASSWORD=postgres psql -h 127.0.0.1 -U postgres postgres -c "SELECT version();" || (echo "!!! Postgres is not running. Please start it with 'docker compose up -d postgres' !!!" && false)
+	POSTGRES_HOST=127.0.0.1 gotestsum $(GOTESTSUM_FLAGS) -- $(GO_TEST_FLAGS) ./...
+
+.PHONY: test-nocache
+test-nocache: ## Run tests without cache
+	$(call print-target)
+	PGPASSWORD=postgres psql -h 127.0.0.1 -U postgres postgres -c "SELECT version();" || (echo "!!! Postgres is not running. Please start it with 'docker compose up -d postgres' !!!" && false)
+	POSTGRES_HOST=127.0.0.1 gotestsum $(GOTESTSUM_FLAGS) -- $(GO_TEST_FLAGS) -count=1 ./...
+
+.PHONY: test-all
+test-all: ## Run tests with svix dependencies, bypassing the test cache
+	$(call print-target)
+	docker compose up -d postgres svix redis
+	./tools/wait-for-compose.sh postgres svix redis
+	SVIX_HOST="localhost" SVIX_JWT_SECRET="$(SVIX_JWT_SECRET)" gotestsum $(GOTESTSUM_FLAGS) -- $(GO_TEST_FLAGS) -count=1 ./...
+
+.PHONY: test-go-sdk
+test-go-sdk: ## Build, vet, and test the v3 Go SDK module (api/v3/client)
+	$(call print-target)
+	cd api/v3/client && go build ./... && go vet ./... && gotestsum $(GOTESTSUM_FLAGS) -- ./...
+
+.PHONY: lint
+lint: lint-go lint-api-spec lint-openapi lint-helm ## Run linters
+	$(call print-target)
+
+.PHONY: lint-api-spec
+lint-api-spec: ## Lint OpenAPI spec
+	$(call print-target)
+	$(MAKE) -C api/spec lint
+
+.PHONY: test-api-spec
+test-api-spec: ## Run AIP TypeScript SDK and emitter tests
+	$(call print-target)
+	$(MAKE) -C api/spec test
+
+.PHONY: lint-openapi
+lint-openapi: ## Lint OpenAPI spec
+	$(call print-target)
+	spectral lint api/openapi.yaml api/openapi.cloud.yaml api/v3/openapi.yaml
+
+.PHONY: lint-helm
+lint-helm: ## Lint Helm charts
+	$(call print-target)
+	helm lint deploy/charts/openmeter
+	helm lint deploy/charts/benthos-collector
+
+# Package a helm chart for release.
+# Usage: make package-helm-chart CHART=openmeter VERSION=v1.2.3
+#   Produces build/helm/<CHART>-<version-without-v>.tgz
+.PHONY: package-helm-chart
+package-helm-chart: ## Package a helm chart for release (set CHART and VERSION)
+	$(call print-target)
+	@if [ -z "$(CHART)" ] || [ -z "$(VERSION)" ]; then echo "ERROR: CHART and VERSION are required"; exit 1; fi
+	@chart_dir="deploy/charts/$(CHART)" && \
+		version_no_v="$(VERSION:v%=%)" && \
+		mkdir -p build/helm && \
+		helm-docs --log-level info -s file -c "$$chart_dir" \
+			-t "deploy/charts/template.md" -t "$$chart_dir/README.tmpl.md" && \
+		helm dependency update "$$chart_dir" && \
+		helm package "$$chart_dir" \
+			--version "$$version_no_v" \
+			--app-version "$(VERSION)" \
+			--destination build/helm
+
+.PHONY: lint-go
+lint-go: ## Lint Go code
+	$(call print-target)
+	golangci-lint run -v $(GO_LINT_PATH)
+	cd api/v3/client && golangci-lint run -v ./...
+	go vet -C e2e ./...
+	cd e2e && golangci-lint run -v ./...
+
+.PHONY: lint-go-fast
+lint-go-fast: ## Lint Go bug-finding checks (set GO_LINT_PATH=./openmeter/ledger/...)
+	$(call print-target)
+	golangci-lint run -v --config .golangci-fast.yaml $(GO_LINT_PATH)
+
+.PHONY: lint-go-style
+lint-go-style: ## Lint Go formatting and import order
+	$(call print-target)
+	golangci-lint fmt -v -d $(GO_LINT_PATH)
+
+.PHONY: lint-go-head
+lint-go-head: ## Lint Go code since last commit
+	$(call print-target)
+	golangci-lint run --new-from-rev=HEAD~1
+
+.PHONY: ci
+ci: ## Run CI checks
+	$(call print-target)
+	$(MAKE) generate-all
+	$(MAKE) -j 10 lint test etoe
+
+.PHONY: fmt
+fmt: ## Format code
+	$(call print-target)
+	golangci-lint run --fix
+
+.PHONY: mod
+mod: ## go mod tidy
+	$(call print-target)
+	go mod tidy
+	go mod tidy -C collector
+	go mod tidy -C api/v3/client
+	go mod tidy -C e2e
+
+.PHONY: seed
+seed: ## Seed OpenMeter with test data
+	$(call print-target)
+	benthos -c etc/seed/seed.yaml
+
+.PHONY: help
+.DEFAULT_GOAL := help
+help:
+	@grep -h -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+# Variable outputting/exporting rules
+var-%: ; @echo $($*)
+varexport-%: ; @echo $*=$($*)
+
+define print-target
+    @printf "Executing target: \033[36m$@\033[0m\n"
+endef

README.md

@@ -1,10 +1,163 @@
 ---
 title: Openmeter
-emoji: 🏃
-colorFrom: blue
-colorTo: red
 sdk: docker
-pinned: false
+app_port: 7860
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<div align="center">
+
+![OpenMeter logo](assets/logo.png)
+
+# OpenMeter
+
+The open-source metering and billing platform
+for AI, agentic and DevTool monetization.
+
+[Docs](https://openmeter.io/docs) |
+[Hosted](https://cloud.konghq.com/register?utm_campaign=metering_and_billing) |
+[Blog](https://openmeter.io/blog) |
+[Contributing](CONTRIBUTING.md)
+
+[![GitHub Release](https://img.shields.io/github/v/release/openmeterio/openmeter?style=flat-square)](https://github.com/openmeterio/openmeter/releases/latest)
+[![CI Status](https://img.shields.io/github/actions/workflow/status/openmeterio/openmeter/ci.yaml?style=flat-square)](https://github.com/openmeterio/openmeter/actions/workflows/ci.yaml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/openmeterio/openmeter?style=flat-square)](https://goreportcard.com/report/github.com/openmeterio/openmeter)
+![GitHub Stars](https://img.shields.io/github/stars/openmeterio/openmeter?style=flat-square)
+
+</div>
+
+---
+
+OpenMeter is a real-time metering and billing engine that
+helps you track usage, enforce limits, manage subscriptions,
+and automate invoicing — all in one platform. Ingest events
+via a simple API, define meters with flexible aggregations,
+and connect usage data to billing, entitlements, and
+customer-facing dashboards.
+
+## Features
+
+- **Usage Metering** — Ingest events in
+  [CloudEvents](https://cloudevents.io) format, define meters
+  with flexible aggregations (SUM, COUNT, AVG, MIN, MAX),
+  and query usage in real time.
+- **Usage-Based Billing** — Generate invoices from metered
+  usage. Supports tiered, graduated, and flat-fee pricing
+  with automated invoice lifecycle management.
+- **Usage Limits and Entitlements** — Enforce usage quotas
+  per feature with real-time balance tracking, boolean
+  feature flags, and grace periods.
+- **Product Catalog** — Define plans, add-ons, features, and
+  rate cards. Manage subscriptions with mid-cycle changes,
+  prorating, and alignment.
+- **Prepaid Credits** — Support paid or promotional credit grants
+  with priority-based burn-down and expiration.
+- **Customer Portal** — Token-based self-service dashboards
+  so your customers can see their own usage.
+- **Notifications** — Webhook-based alerts with configurable
+  rules and channels for usage thresholds and billing events.
+- **LLM Cost Tracking** — First-class support for metering
+  AI token usage and computing model-specific costs.
+
+## Getting Started
+
+### Cloud
+
+The fastest way to start.
+[Start for free](https://cloud.konghq.com/register?utm_campaign=metering_and_billing)
+and begin metering and billing in minutes —
+no infrastructure to manage.
+
+### Self-Hosted
+
+Run OpenMeter locally with Docker Compose:
+
+```sh
+git clone git@github.com:openmeterio/openmeter.git
+cd openmeter/quickstart
+docker compose up -d
+```
+
+Then ingest your first event:
+
+```sh
+curl -X POST http://localhost:48888/api/v1/events \
+  -H 'Content-Type: application/cloudevents+json' \
+  --data-raw '{
+    "specversion": "1.0",
+    "type": "request",
+    "id": "00001",
+    "time": "2026-07-07T00:00:00.001Z",
+    "source": "my-service",
+    "subject": "customer-1",
+    "data": { "method": "GET", "route": "/api/hello" }
+  }'
+```
+
+Query your usage:
+
+```sh
+curl 'http://localhost:48888/api/v1/meters/api_requests_total/query?windowSize=HOUR' | jq
+```
+
+See the full [quickstart guide](/quickstart) for more details.
+
+### Deploy to Production
+
+Deploy to Kubernetes using our
+[Helm chart](https://openmeter.io/docs/deploy/kubernetes).
+
+## SDKs
+
+| Language             | Package                                                                        | Source                                             |
+|----------------------|--------------------------------------------------------------------------------|----------------------------------------------------|
+| Go                   | [openmeter](https://pkg.go.dev/github.com/openmeterio/openmeter/api/client/go) | [api/client/go](/api/client/go)                    |
+| JavaScript / Node.js | [@openmeter/sdk](https://www.npmjs.com/package/@openmeter/sdk)                 | [api/client/javascript](/api/client/javascript)    |
+| Python               | [openmeter](https://pypi.org/project/openmeter)                                | [api/client/python](/api/client/python)            |
+
+Don't see your language? Use the
+[OpenAPI spec](https://github.com/openmeterio/openmeter/blob/main/api/openapi.yaml)
+directly or
+[request an SDK](https://github.com/openmeterio/openmeter/issues/new?assignees=&labels=area%2Fapi%2Ckind%2Ffeature&projects=&template=feature_request.yaml).
+
+## Architecture
+
+OpenMeter is built in Go with a stack optimized for
+high-volume event ingestion and real-time aggregation:
+
+| Component                | Role                                                     |
+|--------------------------|----------------------------------------------------------|
+| **PostgreSQL** (Ent ORM) | Billing, subscriptions, entitlements, product catalog    |
+| **ClickHouse**           | Real-time usage aggregation and analytics                |
+| **Kafka**                | Event streaming and ingestion pipeline                   |
+| **TypeSpec**             | API-first design — OpenAPI spec and SDKs from TypeSpec   |
+
+## Community
+
+We'd love to have you involved:
+
+- **[Contributing](CONTRIBUTING.md)** — Start here if you
+  want to contribute code.
+- **[Code of Conduct](CODE_OF_CONDUCT.md)** — Our community
+  guidelines.
+- **[Blog](https://openmeter.io/blog)** — Product updates
+  and engineering deep dives.
+
+## Development
+
+Prerequisites: [Nix](https://nixos.org/download.html) and
+[direnv](https://direnv.net/docs/installation.html) are
+recommended. See [CONTRIBUTING.md](CONTRIBUTING.md) for
+detailed setup instructions.
+
+```sh
+make up       # Start dependencies (Postgres, Kafka, ClickHouse)
+make server   # Run the API server with hot reload
+make test     # Run tests
+make lint     # Run linters
+```
+
+## License
+
+Licensed under [Apache 2.0](LICENSE).
+
+[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B38090%2Fgithub.com%2Fopenmeterio%2Fopenmeter.svg?type=large)](https://app.fossa.com/projects/custom%2B38090%2Fgithub.com%2Fopenmeterio%2Fopenmeter?ref=badge_large)

SECURITY.md

@@ -0,0 +1,29 @@
+# Security Policies and Procedures
+
+This document outlines security procedures and general policies for OpenMeter.
+
+- [Reporting a vulnerability](#reporting-a-vulnerability)
+- [Disclosure policy](#disclosure-policy)
+
+## Reporting a vulnerability
+
+The OpenMeter team and community take all security issues seriously. Thank you for improving the security of our projects.
+We appreciate your efforts and responsible disclosure and will make every effort to acknowledge your contributions.
+
+**Report security issues using GitHub's [vulnerability reporting feature](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing/privately-reporting-a-security-vulnerability).**
+
+_Alternatively, you can send an email to `security@openmeter.io`._
+
+Somebody from the OpenMeter team will acknowledge your report within 48 hours,
+and will follow up with a more detailed response after that indicating the next steps in handling your report.
+After the initial reply to your report, the team will endeavor to keep you informed of the progress towards a fix and full announcement,
+and may ask for additional information or guidance.
+
+## Disclosure policy
+
+When the team receives a vulnerability report, they will assign it to a primary handler.
+This person will coordinate the fix and release process, involving the following steps:
+
+- Confirm the problem and determine the affected versions.
+- Audit code to find any potential similar problems.
+- Prepare fixes for all releases still under maintenance. These fixes will be released as quickly as possible.

api/api.go

@@ -0,0 +1,2 @@
+//go:generate go tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=codegen.yaml ./openapi.yaml
+package api

api/client/go/README.md

@@ -0,0 +1,65 @@
+# OpenMeter Go SDK
+
+## Install
+
+```sh
+go get github.com/openmeterio/openmeter/api/client/go@v1.0.0-beta.53
+```
+
+## Usage
+
+Initialize client.
+
+```go
+import (
+  cloudevents "github.com/cloudevents/sdk-go/v2/event"
+  om "github.com/openmeterio/openmeter/api/client/go"
+)
+
+func main() {
+  // Initialize OpenMeter client
+  om, err := openmeter.NewClientWithResponses("http://localhost:8888")
+  if err != nil {
+      panic(err.Error())
+  }
+
+  // Use OpenMeter client
+  // ...
+}
+```
+
+### Ingest Event
+
+Report usage to OpenMeter.
+
+```go
+e := cloudevents.New()
+e.SetID("00001")
+e.SetSource("my-app")
+e.SetType("tokens")
+e.SetSubject("user-id")
+e.SetTime(time.Now())
+e.SetData("application/json", map[string]string{
+  "tokens": "15",
+  "model": "gpt-4",
+})
+
+_, err := client.IngestEventWithResponse(ctx, e)
+```
+
+### Query Meter
+
+Retreive usage from OpenMeter.
+
+```go
+slug := "token-usage"
+subject := []string{"user-id"}
+from, _ := time.Parse(time.RFC3339, "2023-01-01T00:00:00Z")
+to, _ := time.Parse(time.RFC3339, "2023-01-02T00:00:00Z")
+resp, _ := client.QueryMeterWithResponse(ctx, slug, &om.QueryMeterParams{
+    Subject: &subject,
+    From:    &from,
+    To:      &to,
+})
+// resp.JSON200.Data
+```

api/client/go/client.go

@@ -0,0 +1,48 @@
+//go:generate go tool github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen --config=codegen.yaml ../../openapi.cloud.yaml
+package openmeter
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+)
+
+func NewAuthClientWithResponses(server string, apiSecret string, opts ...ClientOption) (*ClientWithResponses, error) {
+	o := []ClientOption{WithRequestEditorFn(func(ctx context.Context, req *http.Request) error {
+		req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", apiSecret))
+		return nil
+	})}
+	o = append(opts, o...)
+
+	return NewClientWithResponses(server, o...)
+}
+
+func NewAuthClient(server string, apiSecret string, opts ...ClientOption) (*Client, error) {
+	o := []ClientOption{WithRequestEditorFn(func(ctx context.Context, req *http.Request) error {
+		req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", apiSecret))
+		return nil
+	})}
+	o = append(opts, o...)
+
+	return NewClient(server, o...)
+}
+
+// IngestEvents is a wrapper around generated client's IngestEventsWithApplicationCloudeventsPlusJSONBody
+func (c *Client) IngestEvent(ctx context.Context, event Event, reqEditors ...RequestEditorFn) (*http.Response, error) {
+	return c.IngestEventsWithApplicationCloudeventsPlusJSONBody(ctx, event, reqEditors...)
+}
+
+// IngestEvents is a wrapper around generated client's IngestEventsWithApplicationCloudeventsBatchPlusJSONBody
+func (c *Client) IngestEventBatch(ctx context.Context, events []Event, reqEditors ...RequestEditorFn) (*http.Response, error) {
+	return c.IngestEventsWithApplicationCloudeventsBatchPlusJSONBody(ctx, events, reqEditors...)
+}
+
+// IngestEventsWithResponse is a wrapper around generated client's IngestEventsWithApplicationCloudeventsPlusJSONBodyWithResponse
+func (c *ClientWithResponses) IngestEventWithResponse(ctx context.Context, event Event, reqEditors ...RequestEditorFn) (*IngestEventsResponse, error) {
+	return c.IngestEventsWithApplicationCloudeventsPlusJSONBodyWithResponse(ctx, event, reqEditors...)
+}
+
+// IngestEventsWithResponse is a wrapper around generated client's IngestEventsWithApplicationCloudeventsBatchPlusJSONBodyWithResponse
+func (c *ClientWithResponses) IngestEventBatchWithResponse(ctx context.Context, events []Event, reqEditors ...RequestEditorFn) (*IngestEventsResponse, error) {
+	return c.IngestEventsWithApplicationCloudeventsBatchPlusJSONBodyWithResponse(ctx, events, reqEditors...)
+}

api/client/go/client_test.go

@@ -0,0 +1,327 @@
+package openmeter
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	cloudevents "github.com/cloudevents/sdk-go/v2/event"
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+
+	"github.com/openmeterio/openmeter/openmeter/meter"
+)
+
+func TestIngest(t *testing.T) {
+	ctx := context.Background()
+
+	// Create a mock server to test the client
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPost, r.Method)
+		assert.Equal(t, "/api/v1/events", r.URL.Path)
+		assert.Equal(t, "application/cloudevents+json", r.Header.Get("Content-Type"))
+
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	// Create a client with the mock server
+	om, err := NewClientWithResponses(server.URL)
+	assert.NoError(t, err)
+
+	resp, err := om.IngestEventWithResponse(ctx, mockEvent())
+	assert.NoError(t, err)
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode())
+}
+
+func TestIngestBatch(t *testing.T) {
+	ctx := context.Background()
+
+	// Create a mock server to test the client
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPost, r.Method)
+		assert.Equal(t, "/api/v1/events", r.URL.Path)
+		assert.Equal(t, "application/cloudevents-batch+json", r.Header.Get("Content-Type"))
+
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	// Create a client with the mock server
+	om, err := NewClientWithResponses(server.URL)
+	assert.NoError(t, err)
+
+	resp, err := om.IngestEventBatchWithResponse(ctx, []cloudevents.Event{mockEvent()})
+	assert.NoError(t, err)
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode())
+}
+
+func TetsListEvents(t *testing.T) {
+	ctx := context.Background()
+
+	event := mockEvent()
+
+	// Create a mock server to test the client
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodGet, r.Method)
+		assert.Equal(t, "/api/v1/events", r.URL.Path)
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+
+		err := json.NewEncoder(w).Encode([]Event{event})
+		assert.NoError(t, err)
+	}))
+	defer server.Close()
+
+	// Create a client with the mock server
+	om, err := NewClientWithResponses(server.URL)
+	assert.NoError(t, err)
+
+	resp, err := om.ListEventsWithResponse(ctx, &ListEventsParams{})
+	assert.NoError(t, err)
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode())
+	assert.Equal(t, lo.ToPtr([]Event{event}), resp.JSON200)
+}
+
+func TestAuth(t *testing.T) {
+	ctx := context.Background()
+
+	// Create a mock server to test the client
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPost, r.Method)
+		assert.Equal(t, "/api/v1/events", r.URL.Path)
+		assert.Equal(t, "application/cloudevents+json", r.Header.Get("Content-Type"))
+		assert.Equal(t, "Bearer test-api-token", r.Header.Get("Authorization"))
+
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	// Create a client with the mock server
+	om, err := NewAuthClientWithResponses(server.URL, "test-api-token")
+	assert.NoError(t, err)
+
+	resp, err := om.IngestEventWithResponse(ctx, mockEvent())
+	assert.NoError(t, err)
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode())
+}
+
+func TestGetMeter(t *testing.T) {
+	ctx := context.Background()
+
+	meter := Meter{
+		Slug:          "meter-1",
+		Description:   lo.ToPtr("Test Meter"),
+		Aggregation:   MeterAggregation(meter.MeterAggregationSum),
+		ValueProperty: lo.ToPtr("$.tokens"),
+		GroupBy:       lo.ToPtr(map[string]string{"model": "$.model", "type": "$.type"}),
+	}
+
+	// Create a mock server to test the client
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodGet, r.Method)
+		assert.Equal(t, "/api/v1/meters/meter-1", r.URL.Path)
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+
+		err := json.NewEncoder(w).Encode(meter)
+		assert.NoError(t, err)
+	}))
+	defer server.Close()
+
+	// Create a client with the mock server
+	om, err := NewClientWithResponses(server.URL)
+	assert.NoError(t, err)
+
+	resp, err := om.GetMeterWithResponse(ctx, "meter-1")
+	assert.NoError(t, err)
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode())
+	assert.Equal(t, &meter, resp.JSON200)
+}
+
+func TestListMeters(t *testing.T) {
+	ctx := context.Background()
+
+	meters := []Meter{
+		{
+			Slug:          "meter-1",
+			Description:   lo.ToPtr("Test Meter"),
+			Aggregation:   MeterAggregation(meter.MeterAggregationSum),
+			ValueProperty: lo.ToPtr("$.tokens"),
+			GroupBy:       lo.ToPtr(map[string]string{"model": "$.model", "type": "$.type"}),
+		},
+		{
+			Slug:          "meter-2",
+			Description:   lo.ToPtr("Test Meter 2"),
+			Aggregation:   MeterAggregation(meter.MeterAggregationSum),
+			ValueProperty: lo.ToPtr("$.tokens"),
+			GroupBy:       lo.ToPtr(map[string]string{"model": "$.model", "type": "$.type"}),
+		},
+	}
+
+	// Create a mock server to test the client
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodGet, r.Method)
+		assert.Equal(t, "/api/v1/meters", r.URL.Path)
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+
+		err := json.NewEncoder(w).Encode(meters)
+		assert.NoError(t, err)
+	}))
+	defer server.Close()
+
+	// Create a client with the mock server
+	om, err := NewClientWithResponses(server.URL)
+	assert.NoError(t, err)
+
+	resp, err := om.ListMetersWithResponse(ctx, &ListMetersParams{})
+	assert.NoError(t, err)
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode())
+	assert.Equal(t, &meters, resp.JSON200)
+}
+
+func TestMeterQuery(t *testing.T) {
+	ctx := context.Background()
+
+	result := MeterQueryResult{
+		Data: []MeterQueryRow{
+			{
+				Subject:     lo.ToPtr("customer-1"),
+				WindowStart: time.Now().UTC(),
+				WindowEnd:   time.Now().UTC(),
+				Value:       123,
+			},
+		},
+	}
+
+	// Create a mock server to test the client
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodGet, r.Method)
+		assert.Equal(t, "/api/v1/meters/meter-1/query", r.URL.Path)
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+
+		err := json.NewEncoder(w).Encode(result)
+		assert.NoError(t, err)
+	}))
+	defer server.Close()
+
+	// Create a client with the mock server
+	om, err := NewClientWithResponses(server.URL)
+	assert.NoError(t, err)
+
+	subjectFilter := []string{"customer-1"}
+
+	resp, err := om.QueryMeterWithResponse(ctx, "meter-1", &QueryMeterParams{
+		Subject: &subjectFilter,
+	})
+	assert.NoError(t, err)
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode())
+	assert.Equal(t, &result, resp.JSON200)
+}
+
+func TestListSubjects(t *testing.T) {
+	ctx := context.Background()
+
+	subjects := []Subject{
+		{
+			Key:         "customer-1",
+			DisplayName: lo.ToPtr("Customer 1"),
+		},
+		{
+			Key:         "customer-2",
+			DisplayName: lo.ToPtr("Customer 2"),
+		},
+	}
+
+	// Create a mock server to test the client
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodGet, r.Method)
+		assert.Equal(t, "/api/v1/subjects", r.URL.Path)
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+
+		err := json.NewEncoder(w).Encode(subjects)
+		assert.NoError(t, err)
+	}))
+	defer server.Close()
+
+	// Create a client with the mock server
+	om, err := NewClientWithResponses(server.URL)
+	assert.NoError(t, err)
+
+	resp, err := om.ListSubjectsWithResponse(ctx)
+	assert.NoError(t, err)
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode())
+	assert.Equal(t, &subjects, resp.JSON200)
+}
+
+func TestUpsertSubject(t *testing.T) {
+	ctx := context.Background()
+
+	subject := Subject{
+		Key:         "customer-1",
+		DisplayName: lo.ToPtr("Customer 1"),
+	}
+
+	// Create a mock server to test the client
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, http.MethodPost, r.Method)
+		assert.Equal(t, "/api/v1/subjects", r.URL.Path)
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+
+		err := json.NewEncoder(w).Encode([]Subject{subject})
+		assert.NoError(t, err)
+	}))
+	defer server.Close()
+
+	// Create a client with the mock server
+	om, err := NewClientWithResponses(server.URL)
+	assert.NoError(t, err)
+
+	resp, err := om.UpsertSubjectWithResponse(ctx, []SubjectUpsert{
+		{
+			Key:         "customer-1",
+			DisplayName: lo.ToPtr("Customer 1"),
+		},
+	})
+	assert.NoError(t, err)
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode())
+	assert.Equal(t, lo.ToPtr([]Subject{subject}), resp.JSON200)
+}
+
+// mockEvent creates a mock CloudEvent for testing
+func mockEvent() cloudevents.Event {
+	e := cloudevents.New()
+	eventTime, _ := time.Parse(time.RFC3339, "2024-11-05T22:35:52.457Z")
+	e.SetTime(eventTime)
+	e.SetID("ec2672e8-458d-4c5e-8a3c-f3235dd38ba5")
+	e.SetSource("my-app")
+	e.SetType("usage-reports")
+	e.SetSubject("customer-1")
+	_ = e.SetData("application/json", map[string]string{
+		"reports": "123",
+		"type":    "type",
+	})
+	return e
+}

api/client/go/codegen.yaml

@@ -0,0 +1,11 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/oapi-codegen/oapi-codegen/HEAD/configuration-schema.json
+package: openmeter
+generate:
+  client: true
+  models: true
+  embedded-spec: true
+compatibility:
+  # See: https://github.com/oapi-codegen/oapi-codegen/issues/778
+  disable-required-readonly-as-pointer: true
+  always-prefix-enum-values: true
+output: ./client.gen.go

api/client/go/error.go

@@ -0,0 +1,14 @@
+package openmeter
+
+// ErrResponse renderer type for handling all sorts of errors.
+// In the best case scenario, the excellent github.com/pkg/errors package
+// helps reveal information on the error, setting it on Err, and in the Render()
+// method, using it to set the application-specific error code in AppCode.
+type ErrResponse struct {
+	Err error `json:"-"` // low-level runtime error
+
+	StatusCode int    `json:"statusCode"`        // http response status code
+	StatusText string `json:"status"`            // user-level status message
+	AppCode    int64  `json:"code,omitempty"`    // application-specific error code
+	Message    string `json:"message,omitempty"` // application-level error message, for debugging
+}

api/client/javascript/.gitignore

@@ -0,0 +1,23 @@
+# dot-files (.env, .git, ...)
+
+# logs
+logs
+*.log
+npm-debug.log*
+
+# dependency directory
+# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
+node_modules
+
+# editor
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# build
+.duel-cache/
+tsconfig.tsbuildinfo
+dist/

api/client/javascript/.npmignore

@@ -0,0 +1,27 @@
+# dot-files (.env, .git, .npmrc, ...)
+.*
+
+# logs
+logs
+*.log
+npm-debug.log*
+
+# dependency directory
+# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
+node_modules
+
+# editor
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# source
+index.ts
+src/
+scripts/
+vitest.config.ts
+eslint.config.js
+tsconfig*.json

api/client/javascript/.npmrc

@@ -0,0 +1 @@
+save-exact=true

api/client/javascript/Makefile

@@ -0,0 +1,42 @@
+# A Self-Documenting Makefile: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+
+.PHONY: generate
+generate: ## Generate JavaScript SDK
+	$(call print-target)
+	pnpm --frozen-lockfile install
+	pnpm run generate
+	pnpm build
+	pnpm test
+
+.PHONY: publish-javascript-sdk
+publish-javascript-sdk: ## Publish JavaScript SDK
+	$(call print-target)
+	@if [ -z "$$JS_SDK_RELEASE_VERSION" ]; then \
+		echo "ERROR: JS_SDK_RELEASE_VERSION is required"; \
+		echo "Usage: JS_SDK_RELEASE_VERSION=1.2.3 make publish-javascript-sdk [JS_SDK_RELEASE_TAG=beta]"; \
+		exit 1; \
+	fi
+
+	@if [ -z "$$JS_SDK_RELEASE_TAG" ]; then \
+		echo "ERROR: JS_SDK_RELEASE_TAG is required"; \
+		echo "Usage: JS_SDK_RELEASE_VERSION=1.2.3 make publish-javascript-sdk [JS_SDK_RELEASE_TAG=beta]"; \
+		exit 1; \
+	fi
+
+	pnpm --frozen-lockfile install
+	pnpm version "$${JS_SDK_RELEASE_VERSION}" --no-git-tag-version
+	CACHE_BUSTER="$$(date --rfc-3339=seconds)" pnpm publish --no-git-checks --tag "$${JS_SDK_RELEASE_TAG}"
+	@echo "✅ Published $${JS_SDK_RELEASE_TAG} JavaScript SDK version $${JS_SDK_RELEASE_VERSION} with tag $${JS_SDK_RELEASE_TAG}"
+
+.PHONY: help
+.DEFAULT_GOAL := help
+help:
+	@grep -h -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+# Variable outputting/exporting rules
+var-%: ; @echo $($*)
+varexport-%: ; @echo $*=$($*)
+
+define print-target
+    @printf "Executing target: \033[36m$@\033[0m\n"
+endef

api/client/javascript/README.md

@@ -0,0 +1,267 @@
+# OpenMeter JavaScript SDK
+
+## Install
+
+```sh
+npm install --save @openmeter/sdk
+```
+
+## Configuration for accessing the OpenMeter API
+
+To use the OpenMeter SDK on your backend, you need to configure `baseUrl` and `apiKey` for OpenMeter Cloud:
+
+```ts
+import { OpenMeter } from '@openmeter/sdk'
+
+const openmeter = new OpenMeter({
+  baseUrl: 'https://openmeter.cloud',
+  apiKey: 'om_...',
+})
+```
+
+## Configuration for accessing the OpenMeter Portal API
+
+To use the OpenMeter Portal SDK on your frontend, you need to configure it use a portal token in your configuration:
+
+```ts
+import { OpenMeter } from '@openmeter/sdk/portal'
+
+const openmeter = new OpenMeter({
+  baseUrl: 'https://openmeter.cloud',
+  portalToken: 'om_portal_...',
+})
+```
+
+## Configuration for accessing the OpenMeter React SDK
+
+To use the OpenMeter React SDK for the portal API, you need to configure a Portal Client and a React Context:
+
+```ts
+import {
+  OpenMeter,
+  OpenMeterProvider,
+  useOpenMeter,
+} from '@openmeter/sdk/react'
+
+function App() {
+  // get portal token from your backend
+  const openmeter = new OpenMeter({
+    baseUrl: 'https://openmeter.cloud',
+    portalToken,
+  })
+
+  return (
+    <OpenMeterProvider value={openmeter}>
+      <UsageComponent />
+      {/* ... */}
+    </OpenMeterProvider>
+  )
+}
+
+function UsageComponent() {
+  // get openmeter client from context
+  const openmeter = useOpenMeter()
+
+  // ...
+}
+```
+
+## Ingest usage events
+
+```ts
+// Ingest a single AI token usage event
+await openmeter.events.ingest({
+  type: 'ai-tokens',
+  subject: 'customer-acme-corp',
+  id: 'evt_01234567', // optional: auto-generated if not provided
+  source: 'llm-api-gateway', // optional: defaults to '@openmeter/sdk'
+  time: new Date(), // optional: defaults to current time
+  data: {
+    model: 'gpt-4',
+    type: 'input',
+    tokens: 1250,
+  },
+})
+
+// Ingest multiple events in a batch for better performance
+await openmeter.events.ingest([
+  {
+    type: 'ai-tokens',
+    subject: 'customer-acme-corp',
+    data: { model: 'gpt-4', type: 'input', tokens: 850 },
+  },
+  {
+    type: 'ai-tokens',
+    subject: 'customer-acme-corp',
+    data: { model: 'gpt-4', type: 'output', tokens: 850 },
+  },
+])
+```
+
+## Client API Reference
+
+The OpenMeter SDK provides a comprehensive client interface organized into logical groups. Below is a complete reference of all available methods.
+
+### Overview
+
+| Namespace | Resource | Operation | Method | Description |
+|-----------|----------|-----------|--------|-------------|
+| **[Events](#events)** | | | | Track usage by ingesting events |
+| | Events | Create | [`openmeter.events.ingest(events)`](./src/client/events.ts#L19) | Ingest a single event or batch of events |
+| | Events | Read | [`openmeter.events.list(params?)`](./src/client/events.ts#L41) | List ingested events with advanced filtering |
+| | Events | Read | [`openmeter.events.listV2(params?)`](./src/client/events.ts#L60) | List ingested events with advanced filtering (V2) |
+| **[Meters](#meters)** | | | | Track and aggregate usage data from events |
+| | Meters | Create | [`openmeter.meters.create(meter)`](./src/client/meters.ts#L19) | Create a new meter |
+| | Meters | Read | [`openmeter.meters.get(idOrSlug)`](./src/client/meters.ts#L34) | Get a meter by ID or slug |
+| | Meters | Read | [`openmeter.meters.list()`](./src/client/meters.ts#L55) | List all meters |
+| | Meters | Read | [`openmeter.meters.query(idOrSlug, query?)`](./src/client/meters.ts#L70) | Query usage data |
+| | Meters | Update | [`openmeter.meters.update(idOrSlug, meter)`](./src/client/meters.ts#L100) | Update a meter by ID or slug |
+| | Meters | Delete | [`openmeter.meters.delete(idOrSlug)`](./src/client/meters.ts#L124) | Delete a meter by ID or slug |
+| **[Subjects](#subjects)** | | | | Manage entities that consume resources |
+| | Subjects | Create | [`openmeter.subjects.upsert(subjects)`](./src/client/subjects.ts#L21) | Create or update one or multiple subjects |
+| | Subjects | Read | [`openmeter.subjects.get(idOrKey)`](./src/client/subjects.ts#L39) | Get a subject by ID or key |
+| | Subjects | Read | [`openmeter.subjects.list()`](./src/client/subjects.ts#L60) | List all subjects |
+| | Subjects | Delete | [`openmeter.subjects.delete(idOrKey)`](./src/client/subjects.ts#L74) | Delete a subject by ID or key |
+| **[Customers](#customers)** | | | | Manage customer subscription lifecycles and plan assignments |
+| | Customers | Create | [`openmeter.customers.create(customer)`](./src/client/customers.ts#L37) | Create a new customer |
+| | Customers | Read | [`openmeter.customers.get(customerIdOrKey)`](./src/client/customers.ts#L52) | Get a customer by ID or key |
+| | Customers | Read | [`openmeter.customers.list(query?)`](./src/client/customers.ts#L123) | List all customers |
+| | Customers | Read | [`openmeter.customers.getAccess(customerIdOrKey)`](./src/client/customers.ts#L143) | Get customer access information |
+| | Customers | Read | [`openmeter.customers.listSubscriptions(customerIdOrKey, query?)`](./src/client/customers.ts#L169) | List customer subscriptions |
+| | Customers | Update | [`openmeter.customers.update(customerIdOrKey, customer)`](./src/client/customers.ts#L75) | Update a customer |
+| | Customers | Delete | [`openmeter.customers.delete(customerIdOrKey)`](./src/client/customers.ts#L99) | Delete a customer |
+| | Apps | Update | [`openmeter.customers.apps.upsert(customerIdOrKey, appData)`](./src/client/customers.ts#L200) | Upsert app data |
+| | Apps | Read | [`openmeter.customers.apps.list(customerIdOrKey)`](./src/client/customers.ts#L228) | List app data |
+| | Apps | Delete | [`openmeter.customers.apps.delete(customerIdOrKey, appId)`](./src/client/customers.ts#L254) | Delete app data |
+| | Stripe | Update | [`openmeter.customers.stripe.upsert(customerIdOrKey, appDataBase)`](./src/client/customers.ts#L285) | Upsert Stripe app data |
+| | Stripe | Read | [`openmeter.customers.stripe.get(customerIdOrKey)`](./src/client/customers.ts#L313) | Get Stripe app data |
+| | Stripe | Create | [`openmeter.customers.stripe.createPortalSession(customerIdOrKey, params)`](./src/client/customers.ts#L337) | Create a Stripe customer portal session |
+| | Entitlements V1 | Read | [`openmeter.customers.entitlementsV1.value(customerIdOrKey, featureKey)`](./src/client/customers.ts#L372) | Get entitlement value (V1 API) |
+| | Entitlements | Read | [`openmeter.customers.entitlements.list(customerIdOrKey)`](./src/client/customers.ts#L401) | List entitlements |
+| | Entitlements | Create | [`openmeter.customers.entitlements.create(customerIdOrKey, entitlement)`](./src/client/customers.ts#L428) | Create an entitlement |
+| | Entitlements | Read | [`openmeter.customers.entitlements.get(customerIdOrKey, featureKeyOrId)`](./src/client/customers.ts#L454) | Get an entitlement |
+| | Entitlements | Delete | [`openmeter.customers.entitlements.delete(customerIdOrKey, entitlementId)`](./src/client/customers.ts#L479) | Delete an entitlement |
+| | Entitlements | Update | [`openmeter.customers.entitlements.override(customerIdOrKey, featureKeyOrId, entitlement)`](./src/client/customers.ts#L505) | Override an entitlement |
+| | Entitlements | Read | [`openmeter.customers.entitlements.value(customerIdOrKey, featureKeyOrId, query?)`](./src/client/customers.ts#L588) | Get entitlement value |
+| | Entitlements | Read | [`openmeter.customers.entitlements.history(customerIdOrKey, featureKeyOrId, query?)`](./src/client/customers.ts#L617) | Get entitlement history |
+| | Entitlements | Update | [`openmeter.customers.entitlements.resetUsage(customerIdOrKey, entitlementId, body?)`](./src/client/customers.ts#L653) | Reset usage |
+| | Entitlements | Read | [`openmeter.customers.entitlements.listGrants(customerIdOrKey, featureKeyOrId, query?)`](./src/client/customers.ts#L532) | List grants |
+| | Entitlements | Create | [`openmeter.customers.entitlements.createGrant(customerIdOrKey, featureKeyOrId, grant)`](./src/client/customers.ts#L561) | Create a grant |
+| **[Features](#features)** | | | | Define application capabilities and services |
+| | Features | Create | [`openmeter.features.create(feature)`](./src/client/features.ts#L24) | Create a new feature |
+| | Features | Read | [`openmeter.features.get(featureIdOrKey)`](./src/client/features.ts#L39) | Get a feature by ID |
+| | Features | Read | [`openmeter.features.list(params?)`](./src/client/features.ts#L61) | List all features |
+| | Features | Delete | [`openmeter.features.delete(featureIdOrKey)`](./src/client/features.ts#L84) | Delete a feature by ID |
+| **[Entitlements (V1)](#entitlements-v1)** | | | | Subject-based usage limits and access controls |
+| | Entitlements | Create | [`openmeter.entitlementsV1.create(subjectIdOrKey, entitlement)`](./src/client/entitlements.ts#L40) | Create an entitlement for a subject |
+| | Entitlements | Read | [`openmeter.entitlementsV1.get(entitlementId)`](./src/client/entitlements.ts#L68) | Get an entitlement by ID |
+| | Entitlements | Read | [`openmeter.entitlementsV1.list(query?)`](./src/client/entitlements.ts#L91) | List all entitlements |
+| | Entitlements | Read | [`openmeter.entitlementsV1.value(subjectIdOrKey, featureIdOrKey, query?)`](./src/client/entitlements.ts#L147) | Get the value of an entitlement |
+| | Entitlements | Read | [`openmeter.entitlementsV1.history(subjectIdOrKey, entitlementIdOrFeatureKey, query?)`](./src/client/entitlements.ts#L180) | Get the history of an entitlement |
+| | Entitlements | Update | [`openmeter.entitlementsV1.override(subjectIdOrKey, entitlementIdOrFeatureKey, override)`](./src/client/entitlements.ts#L213) | Override an entitlement |
+| | Entitlements | Update | [`openmeter.entitlementsV1.reset(subjectIdOrKey, entitlementIdOrFeatureKey, reset?)`](./src/client/entitlements.ts#L247) | Reset entitlement usage |
+| | Entitlements | Delete | [`openmeter.entitlementsV1.delete(subjectIdOrKey, entitlementId)`](./src/client/entitlements.ts#L116) | Delete an entitlement |
+| | Grants | Create | [`openmeter.entitlementsV1.grants.create(subjectIdOrKey, entitlementIdOrFeatureKey, grant)`](./src/client/entitlements.ts#L283) | Create a grant for an entitlement |
+| | Grants | Read | [`openmeter.entitlementsV1.grants.list(subjectIdOrKey, entitlementIdOrFeatureKey, query?)`](./src/client/entitlements.ts#L314) | List grants for an entitlement |
+| | Grants | Read | [`openmeter.entitlementsV1.grants.listAll(query?)`](./src/client/entitlements.ts#L345) | List all grants |
+| | Grants | Delete | [`openmeter.entitlementsV1.grants.void(entitlementId, grantId)`](./src/client/entitlements.ts#L369) | Void a grant |
+| **[Entitlements](#entitlements)** | | | | Customer-based entitlements and access controls |
+| | Entitlements | Read | [`openmeter.entitlements.list(query?)`](./src/client/entitlements.ts#L404) | List all entitlements (admin purposes) |
+| | Entitlements | Read | [`openmeter.entitlements.get(entitlementId)`](./src/client/entitlements.ts#L425) | Get an entitlement by ID |
+| | Grants | Read | [`openmeter.entitlements.grants.list(query?)`](./src/client/entitlements.ts#L453) | List all grants (admin purposes) |
+| | Grants | Delete | [`openmeter.entitlements.grants.void(grantId)`](./src/client/entitlements.ts#L478) | Void a grant |
+| **[Plans](#plans)** | | | | Manage subscription plans and pricing|
+| | Plans | Create | [`openmeter.plans.create(plan)`](./src/client/plans.ts#L28) | Create a new plan|
+| | Plans | Read | [`openmeter.plans.get(planId)`](./src/client/plans.ts#L44) | Get a plan by ID|
+| | Plans | Read | [`openmeter.plans.list(query?)`](./src/client/plans.ts#L66) | List all plans|
+| | Plans | Update | [`openmeter.plans.update(planId, plan)`](./src/client/plans.ts#L85) | Update a plan|
+| | Plans | Delete | [`openmeter.plans.delete(planId)`](./src/client/plans.ts#L105) | Delete a plan by ID|
+| | Plans | Other | [`openmeter.plans.archive(planId)`](./src/client/plans.ts#L123) | Archive a plan|
+| | Plans | Other | [`openmeter.plans.publish(planId)`](./src/client/plans.ts#L141) | Publish a plan|
+| | Addons | Read | [`openmeter.plans.addons.list(planId)`](./src/client/plans.ts#L168) | List addons|
+| | Addons | Create | [`openmeter.plans.addons.create(planId, addon)`](./src/client/plans.ts#L191) | Create an addon|
+| | Addons | Read | [`openmeter.plans.addons.get(planId, planAddonId)`](./src/client/plans.ts#L212) | Get an addon by ID|
+| | Addons | Update | [`openmeter.plans.addons.update(planId, planAddonId, addon)`](./src/client/plans.ts#L238) | Update an addon|
+| | Addons | Delete | [`openmeter.plans.addons.delete(planId, planAddonId)`](./src/client/plans.ts#L263) | Delete an addon by ID|
+| **[Addons](#addons)** | | | | Manage standalone addons available across plans|
+| | Addons | Create | [`openmeter.addons.create(addon)`](./src/client/addons.ts#L15) | Create a new addon|
+| | Addons | Read | [`openmeter.addons.get(addonId)`](./src/client/addons.ts#L48) | Get an addon by ID|
+| | Addons | Read | [`openmeter.addons.list(query?)`](./src/client/addons.ts#L30) | List all addons|
+| | Addons | Update | [`openmeter.addons.update(addonId, addon)`](./src/client/addons.ts#L64) | Update an addon|
+| | Addons | Delete | [`openmeter.addons.delete(addonId)`](./src/client/addons.ts#L84) | Delete an addon by ID|
+| | Addons | Other | [`openmeter.addons.publish(addonId)`](./src/client/addons.ts#L99) | Publish an addon|
+| | Addons | Other | [`openmeter.addons.archive(addonId)`](./src/client/addons.ts#L114) | Archive an addon|
+| **[Subscriptions](#subscriptions)** | | | | Manage customer subscriptions|
+| | Subscriptions | Create | [`openmeter.subscriptions.create(body)`](./src/client/subscriptions.ts#L24) | Create a new subscription|
+| | Subscriptions | Read | [`openmeter.subscriptions.get(subscriptionId)`](./src/client/subscriptions.ts#L39) | Get a subscription by ID|
+| | Subscriptions | Update | [`openmeter.subscriptions.edit(subscriptionId, body)`](./src/client/subscriptions.ts#L61) | Edit a subscription|
+| | Subscriptions | Delete | [`openmeter.subscriptions.delete(subscriptionId)`](./src/client/subscriptions.ts#L180) | Delete a subscription (only scheduled)|
+| | Subscriptions | Other | [`openmeter.subscriptions.cancel(subscriptionId, body?)`](./src/client/subscriptions.ts#L85) | Cancel a subscription|
+| | Subscriptions | Other | [`openmeter.subscriptions.change(subscriptionId, body)`](./src/client/subscriptions.ts#L110) | Change a subscription (upgrade/downgrade)|
+| | Subscriptions | Other | [`openmeter.subscriptions.migrate(subscriptionId, body)`](./src/client/subscriptions.ts#L135) | Migrate to a new plan version|
+| | Subscriptions | Other | [`openmeter.subscriptions.unscheduleCancelation(subscriptionId)`](./src/client/subscriptions.ts#L158) | Unschedule a subscription cancelation|
+| **[Subscription Addons](#subscription-addons)** | | | | Manage addons attached to specific subscriptions|
+| | Subscription Addons | Create | [`openmeter.subscriptionAddons.create(subscriptionId, body)`](./src/client/subscription-addons.ts#L16) | Create a new subscription addon|
+| | Subscription Addons | Read | [`openmeter.subscriptionAddons.get(subscriptionId, subscriptionAddonId)`](./src/client/subscription-addons.ts#L58) | Get a subscription addon by ID|
+| | Subscription Addons | Read | [`openmeter.subscriptionAddons.list(subscriptionId)`](./src/client/subscription-addons.ts#L39) | List all addons of a subscription|
+| | Subscription Addons | Update | [`openmeter.subscriptionAddons.update(subscriptionId, subscriptionAddonId, body)`](./src/client/subscription-addons.ts#L82) | Update a subscription addon|
+| **[Billing](#billing)** | | | | Comprehensive billing management (profiles, invoices, overrides)|
+| | Profiles | Create | [`openmeter.billing.profiles.create(profile)`](./src/client/billing.ts#L42) | Create a billing profile|
+| | Profiles | Read | [`openmeter.billing.profiles.get(id)`](./src/client/billing.ts#L60) | Get a billing profile by ID|
+| | Profiles | Read | [`openmeter.billing.profiles.list(query?)`](./src/client/billing.ts#L80) | List billing profiles|
+| | Profiles | Update | [`openmeter.billing.profiles.update(id, profile)`](./src/client/billing.ts#L101) | Update a billing profile|
+| | Profiles | Delete | [`openmeter.billing.profiles.delete(id)`](./src/client/billing.ts#L123) | Delete a billing profile|
+| | Invoices | Read | [`openmeter.billing.invoices.list(query?)`](./src/client/billing.ts#L150) | List invoices|
+| | Invoices | Read | [`openmeter.billing.invoices.get(id, query?)`](./src/client/billing.ts#L170) | Get an invoice by ID|
+| | Invoices | Update | [`openmeter.billing.invoices.update(id, invoice)`](./src/client/billing.ts#L192) | Update an invoice (draft or earlier)|
+| | Invoices | Delete | [`openmeter.billing.invoices.delete(id)`](./src/client/billing.ts#L213) | Delete an invoice (draft or earlier)|
+| | Invoices | Other | [`openmeter.billing.invoices.advance(id)`](./src/client/billing.ts#L235) | Advance invoice to next status|
+| | Invoices | Other | [`openmeter.billing.invoices.approve(id)`](./src/client/billing.ts#L257) | Approve an invoice (sends to customer)|
+| | Invoices | Other | [`openmeter.billing.invoices.retry(id, body?)`](./src/client/billing.ts#L278) | Retry advancing after failure|
+| | Invoices | Other | [`openmeter.billing.invoices.void(id)`](./src/client/billing.ts#L302) | Void an invoice|
+| | Invoices | Other | [`openmeter.billing.invoices.recalculateTax(id)`](./src/client/billing.ts#L325) | Recalculate invoice tax amounts|
+| | Invoices | Other | [`openmeter.billing.invoices.simulate(customerId, query?)`](./src/client/billing.ts#L346) | Simulate an invoice for a customer|
+| | Invoices | Create | [`openmeter.billing.invoices.createLineItems(customerId, body)`](./src/client/billing.ts#L377) | Create pending line items|
+| | Invoices | Create | [`openmeter.billing.invoices.invoicePendingLines(customerId)`](./src/client/billing.ts#L401) | Invoice pending lines|
+| | Customers | Create | [`openmeter.billing.customers.createOverride(customerId, body)`](./src/client/billing.ts#L427) | Create or update a customer override|
+| | Customers | Read | [`openmeter.billing.customers.getOverride(customerId, id)`](./src/client/billing.ts#L450) | Get a customer override|
+| | Customers | Read | [`openmeter.billing.customers.listOverrides(customerId)`](./src/client/billing.ts#L471) | List customer overrides|
+| | Customers | Delete | [`openmeter.billing.customers.deleteOverride(customerId, id)`](./src/client/billing.ts#L489) | Delete a customer override|
+| **[Apps](#apps)** | | | | Manage integrations and app marketplace|
+| | Apps | Read | [`openmeter.apps.list(query?)`](./src/client/apps.ts#L32) | List installed apps|
+| | Apps | Read | [`openmeter.apps.get(id)`](./src/client/apps.ts#L50) | Get an app by ID|
+| | Apps | Update | [`openmeter.apps.update(id, body)`](./src/client/apps.ts#L69) | Update an app|
+| | Apps | Delete | [`openmeter.apps.uninstall(id)`](./src/client/apps.ts#L89) | Uninstall an app|
+| | Marketplace | Read | [`openmeter.apps.marketplace.list(query?)`](./src/client/apps.ts#L115) | List available marketplace apps|
+| | Marketplace | Read | [`openmeter.apps.marketplace.get(id)`](./src/client/apps.ts#L133) | Get marketplace listing details|
+| | Marketplace | Read | [`openmeter.apps.marketplace.getOauth2InstallUrl(id, redirectUrl)`](./src/client/apps.ts#L151) | Get OAuth2 install URL|
+| | Marketplace | Other | [`openmeter.apps.marketplace.authorizeOauth2(id, body)`](./src/client/apps.ts#L172) | Authorize OAuth2 code|
+| | Marketplace | Create | [`openmeter.apps.marketplace.installWithAPIKey(id, body)`](./src/client/apps.ts#L193) | Install app with API key|
+| | Stripe | Create | [`openmeter.apps.stripe.createCheckoutSession(body)`](./src/client/apps.ts#L223) | Create a Stripe checkout session|
+| | Stripe | Update | [`openmeter.apps.stripe.updateApiKey(body)`](./src/client/apps.ts#L243) | Update Stripe API key|
+| | Custom Invoicing | Other | [`openmeter.apps.customInvoicing.draftSynchronized(body)`](./src/client/apps.ts#L271) | Submit draft synchronization results|
+| | Custom Invoicing | Other | [`openmeter.apps.customInvoicing.issuingSynchronized(body)`](./src/client/apps.ts#L295) | Submit issuing synchronization results|
+| | Custom Invoicing | Update | [`openmeter.apps.customInvoicing.updatePaymentStatus(invoiceId, body)`](./src/client/apps.ts#L319) | Update payment status|
+| **[Notifications](#notifications)** | | | | Set up automated notifications for usage thresholds|
+| | Channels | Create | [`openmeter.notifications.channels.create(channel)`](./src/client/notifications.ts#L40) | Create a notification channel|
+| | Channels | Read | [`openmeter.notifications.channels.get(channelId)`](./src/client/notifications.ts#L58) | Get a notification channel by ID|
+| | Channels | Update | [`openmeter.notifications.channels.update(channelId, channel)`](./src/client/notifications.ts#L84) | Update a notification channel|
+| | Channels | Read | [`openmeter.notifications.channels.list(query?)`](./src/client/notifications.ts#L111) | List notification channels|
+| | Channels | Delete | [`openmeter.notifications.channels.delete(channelId)`](./src/client/notifications.ts#L131) | Delete a notification channel|
+| | Rules | Create | [`openmeter.notifications.rules.create(rule)`](./src/client/notifications.ts#L164) | Create a notification rule|
+| | Rules | Read | [`openmeter.notifications.rules.get(ruleId)`](./src/client/notifications.ts#L182) | Get a notification rule by ID|
+| | Rules | Update | [`openmeter.notifications.rules.update(ruleId, rule)`](./src/client/notifications.ts#L205) | Update a notification rule|
+| | Rules | Read | [`openmeter.notifications.rules.list(query?)`](./src/client/notifications.ts#L229) | List notification rules|
+| | Rules | Delete | [`openmeter.notifications.rules.delete(ruleId)`](./src/client/notifications.ts#L249) | Delete a notification rule|
+| | Events | Read | [`openmeter.notifications.events.get(eventId)`](./src/client/notifications.ts#L282) | Get a notification event by ID|
+| | Events | Read | [`openmeter.notifications.events.list(query?)`](./src/client/notifications.ts#L307) | List notification events|
+| **[Portal](#portal)** | | | | Manage consumer portal tokens for customer-facing interfaces|
+| | Portal | Create | [`openmeter.portal.create(body)`](./src/client/portal.ts#L19) | Create a consumer portal token|
+| | Portal | Read | [`openmeter.portal.list(query?)`](./src/client/portal.ts#L34) | List consumer portal tokens|
+| | Portal | Other | [`openmeter.portal.invalidate(query?)`](./src/client/portal.ts#L52) | Invalidate consumer portal tokens|
+| **[Info](#info)** | | | | Utility endpoints for system information|
+| | Info | Read | [`openmeter.info.listCurrencies()`](./src/client/info.ts#L18) | List all supported currencies|
+| | Info | Read | [`openmeter.info.getProgress(id)`](./src/client/info.ts#L32) | Get progress of a long-running operation|
+| **[Debug](#debug)** | | | | Debug utilities for monitoring and troubleshooting|
+| | Debug | Read | [`openmeter.debug.getMetrics()`](./src/client/debug.ts#L18) | Get event ingestion metrics (OpenMetrics format)|
+

api/client/javascript/biome.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on",
+        "useSortedKeys": "on"
+      }
+    }
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "includes": ["**"],
+    "maxSize": 20000000
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "useEditorconfig": true
+  },
+  "javascript": {
+    "formatter": {
+      "arrowParentheses": "always",
+      "attributePosition": "auto",
+      "lineWidth": 80,
+      "quoteStyle": "single",
+      "semicolons": "asNeeded",
+      "trailingCommas": "all"
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "style": {
+        "noInferrableTypes": "error",
+        "noParameterAssign": "error",
+        "noUnusedTemplateLiteral": "error",
+        "noUselessElse": "error",
+        "useAsConstAssertion": "error",
+        "useConst": "error",
+        "useDefaultParameterLast": "error",
+        "useEnumInitializers": "error",
+        "useNumberNamespace": "error",
+        "useSelfClosingElements": "error",
+        "useSingleVarDeclarator": "error"
+      }
+    }
+  },
+  "overrides": [
+    {
+      "assist": {
+        "actions": {
+          "source": {
+            "useSortedKeys": "off"
+          }
+        }
+      },
+      "includes": ["package.json"]
+    }
+  ],
+  "vcs": {
+    "clientKind": "git",
+    "enabled": true,
+    "useIgnoreFile": true
+  }
+}

api/client/javascript/index.ts

@@ -0,0 +1 @@
+export * from './src/client/index.js'

api/client/javascript/orval.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig } from 'orval'
+
+export default defineConfig({
+  openmeter: {
+    input: {
+      target: '../../openapi.cloud.yaml',
+    },
+    output: {
+      formatter: 'biome',
+      clean: true,
+      client: 'zod',
+      mode: 'single',
+      namingConvention: 'PascalCase',
+      override: {
+        useDates: true,
+        zod: {
+          coerce: {
+            body: true,
+            header: false,
+            param: true,
+            query: true,
+            response: false,
+          },
+          generate: {
+            body: true,
+            header: false,
+            param: true,
+            query: true,
+            response: false,
+          },
+        },
+      },
+      propertySortOrder: 'Alphabetical',
+      target: './src/zod/index.ts',
+      tsconfig: './tsconfig.json',
+    },
+  },
+})

api/client/javascript/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@openmeter/sdk",
+  "version": "0.0.0",
+  "description": "Client for OpenMeter: Real-Time and Scalable Usage Metering",
+  "license": "Apache 2.0",
+  "homepage": "https://openmeter.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openmeterio/openmeter.git",
+    "directory": "api/client/javascript"
+  },
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      },
+      "default": "./dist/index.js"
+    },
+    "./portal": {
+      "import": {
+        "types": "./dist/src/portal/index.d.ts",
+        "default": "./dist/src/portal/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/src/portal/index.d.cts",
+        "default": "./dist/cjs/src/portal/index.cjs"
+      },
+      "default": "./dist/src/portal/index.js"
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/src/react/context.d.ts",
+        "default": "./dist/src/react/context.js"
+      },
+      "default": "./dist/src/react/context.js"
+    },
+    "./zod": {
+      "import": {
+        "types": "./dist/src/zod/index.d.ts",
+        "default": "./dist/src/zod/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/src/zod/index.d.cts",
+        "default": "./dist/cjs/src/zod/index.cjs"
+      },
+      "default": "./dist/src/zod/index.js"
+    }
+  },
+  "scripts": {
+    "build": "duel",
+    "format": "biome format --write .",
+    "generate": "pnpm run generate:client && pnpm run generate:zod",
+    "generate:client": "tsx scripts/generate.ts && biome format --write ./src/client/schemas.ts",
+    "generate:zod": "orval && tsx scripts/add-as-const.ts && biome lint --write ./src/zod/index.ts && biome format --write ./src/zod/index.ts",
+    "lint": "tsc --noEmit && biome lint .",
+    "prepublishOnly": "pnpm run generate && pnpm run build && pnpm run lint && pnpm run test",
+    "pretest": "pnpm run build",
+    "test": "vitest --run",
+    "test:watch": "vitest --watch"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "openapi-fetch": "0.17.0",
+    "openapi-typescript-helpers": "0.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@fetch-mock/vitest": "0.2.18",
+    "@knighted/duel": "4.1.0",
+    "@types/node": "25.9.2",
+    "@types/node-fetch": "2.6.13",
+    "@types/react": "19.2.17",
+    "fetch-mock": "12.6.0",
+    "openapi-typescript": "7.13.0",
+    "orval": "8.15.0",
+    "prettier": "3.8.3",
+    "react": "19.2.7",
+    "rollup": "4.61.1",
+    "tslib": "2.8.1",
+    "tsx": "4.22.4",
+    "typescript": "5.9.3",
+    "vitest": "4.1.8",
+    "zod": "4.4.3"
+  },
+  "packageManager": "pnpm@11.1.2+sha512.415a1cc25974731e75455c1468371be74c5aa5fb7621b50d4056d222451609f11412f23fd602e6169f1e060466641f798597e1be961a10688836a67b16569499",
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  }
+}

api/client/javascript/pnpm-workspace.yaml

@@ -0,0 +1,10 @@
+blockExoticSubdeps: true
+minimumReleaseAge: 4320
+trustPolicy: no-downgrade
+patchedDependencies:
+  openapi-typescript: patches/openapi-typescript.patch
+overrides:
+  'vite@>=7.0.0 <=7.3.1': '>=7.3.2'
+  'vite@>=7.1.0 <=7.3.1': '>=7.3.2'
+allowBuilds:
+  esbuild: true

api/client/javascript/scripts/add-as-const.ts

@@ -0,0 +1,16 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+
+/**
+ * Post-generation workaround for orval's zod output: object-literal defaults
+ * are emitted without `as const`, so property values widen to `string` and
+ * fail Zod's `.default()` signature when the schema expects a literal type.
+ * Remove this script once orval emits `as const` for object-literal defaults.
+ * See: https://github.com/orval-labs/orval/issues/3244
+ */
+const file = new URL('../src/zod/index.ts', import.meta.url)
+const src = readFileSync(file, 'utf8')
+const fixed = src.replace(
+  /(^export const \w+Default =\s*\{[^{}]*\})/gm,
+  '$1 as const',
+)
+writeFileSync(file, fixed)

api/client/javascript/scripts/generate.ts

@@ -0,0 +1,51 @@
+import fs from 'node:fs'
+import openapiTS, { astToString } from 'openapi-typescript'
+import { factory, SyntaxKind } from 'typescript'
+
+const DATE = factory.createTypeReferenceNode(factory.createIdentifier('Date')) // `Date`
+const NULL = factory.createLiteralTypeNode(factory.createNull()) // `null`
+const STRING = factory.createKeywordTypeNode(SyntaxKind.StringKeyword) // `string`
+
+const schema = new URL('../../../openapi.cloud.yaml', import.meta.url)
+
+const ast = await openapiTS(schema, {
+  defaultNonNullable: false,
+  rootTypes: true,
+  rootTypesNoSchemaPrefix: true,
+  transform(schemaObject, metadata) {
+    if (metadata.path === '#/components/schemas/Event') {
+      if (
+        schemaObject.type === 'string' &&
+        !schemaObject.nullable &&
+        !['customer-id', 'com.example.someevent'].includes(schemaObject.example)
+      ) {
+        return {
+          questionToken: true,
+          schema: STRING,
+        }
+      }
+    }
+    if (schemaObject.format === 'date-time') {
+      const allowString =
+        (metadata.schema &&
+          'in' in metadata.schema &&
+          metadata.schema.in === 'query') ||
+        metadata.path?.includes('/parameters/query')
+
+      // allow string in query parameters
+      if (allowString) {
+        return schemaObject.nullable
+          ? factory.createUnionTypeNode([DATE, NULL, STRING])
+          : factory.createUnionTypeNode([DATE, STRING])
+      }
+
+      return schemaObject.nullable
+        ? factory.createUnionTypeNode([DATE, NULL])
+        : DATE
+    }
+  },
+})
+
+const contents = astToString(ast)
+
+fs.writeFileSync('./src/client/schemas.ts', contents)

api/client/javascript/src/client/addons.ts

@@ -0,0 +1,122 @@
+import type { Client } from 'openapi-fetch'
+import type { RequestOptions } from './common.js'
+import type { AddonCreate, operations, paths } from './schemas.js'
+import { transformResponse } from './utils.js'
+
+export class Addons {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * Create a addon
+   * @param addon - The addon to create
+   * @param options - Optional request options
+   * @returns The created addon
+   */
+  public async create(addon: AddonCreate, options?: RequestOptions) {
+    const resp = await this.client.POST('/api/v1/addons', {
+      body: addon,
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * List addons
+   * @param params - Optional parameters for listing addons
+   * @param options - Optional request options
+   * @returns A list of addons
+   */
+  public async list(
+    params?: operations['listAddons']['parameters']['query'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/addons', {
+      params: { query: params },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get an addon by ID
+   * @param addonId - The ID of the addon to retrieve
+   * @param options - Optional request options
+   * @returns The addon
+   */
+  public async get(addonId: string, options?: RequestOptions) {
+    const resp = await this.client.GET('/api/v1/addons/{addonId}', {
+      params: { path: { addonId } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Update an addon
+   * @param addonId - The ID of the addon to update
+   * @param addon - The addon data to update
+   * @param options - Optional request options
+   * @returns The updated addon
+   */
+  public async update(
+    addonId: string,
+    addon: operations['updateAddon']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT('/api/v1/addons/{addonId}', {
+      body: addon,
+      params: { path: { addonId } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Delete an addon by ID
+   * @param addonId - The ID of the addon to delete
+   * @param options - Optional request options
+   * @returns void or standard error response structure
+   */
+  public async delete(addonId: string, options?: RequestOptions) {
+    const resp = await this.client.DELETE('/api/v1/addons/{addonId}', {
+      params: { path: { addonId } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Publish an addon
+   * @param addonId - The ID of the addon to publish
+   * @param options - Optional request options
+   * @returns The published addon
+   */
+  public async publish(addonId: string, options?: RequestOptions) {
+    const resp = await this.client.POST('/api/v1/addons/{addonId}/publish', {
+      params: { path: { addonId } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Archive an addon
+   * @param addonId - The ID of the addon to archive
+   * @param options - Optional request options
+   * @returns The archived addon
+   */
+  public async archive(addonId: string, options?: RequestOptions) {
+    const resp = await this.client.POST('/api/v1/addons/{addonId}/archive', {
+      params: { path: { addonId } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+}

api/client/javascript/src/client/apps.ts

@@ -0,0 +1,335 @@
+import type { Client } from 'openapi-fetch'
+import type { RequestOptions } from './common.js'
+import type {
+  AppReplaceUpdate,
+  CreateStripeCheckoutSessionRequest,
+  operations,
+  paths,
+} from './schemas.js'
+import { transformResponse } from './utils.js'
+
+/**
+ * Apps
+ * Manage integrations for extending OpenMeter's functionality.
+ */
+export class Apps {
+  public marketplace: AppMarketplace
+  public stripe: AppStripe
+  public customInvoicing: AppCustomInvoicing
+
+  constructor(private client: Client<paths, `${string}/${string}`>) {
+    this.marketplace = new AppMarketplace(client)
+    this.stripe = new AppStripe(client)
+    this.customInvoicing = new AppCustomInvoicing(client)
+  }
+
+  /**
+   * List apps
+   * @param query - The query parameters
+   * @param signal - An optional abort signal
+   * @returns The apps
+   */
+  public async list(
+    query?: operations['listApps']['parameters']['query'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/apps', {
+      params: { query },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get an app
+   * @param id - The ID of the app
+   * @param signal - An optional abort signal
+   * @returns The app
+   */
+  public async get(
+    id: operations['getApp']['parameters']['path']['id'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/apps/{id}', {
+      params: { path: { id } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Update an app
+   * @param id - The ID of the app
+   * @param body - The body of the request
+   * @param signal - An optional abort signal
+   * @returns The app
+   */
+  public async update(
+    id: operations['updateApp']['parameters']['path']['id'],
+    body: AppReplaceUpdate,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT('/api/v1/apps/{id}', {
+      body,
+      params: { path: { id } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Uninstall an app
+   * @param id - The ID of the app
+   * @param signal - An optional abort signal
+   * @returns The app
+   */
+  public async uninstall(
+    id: operations['uninstallApp']['parameters']['path']['id'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.DELETE('/api/v1/apps/{id}', {
+      params: { path: { id } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+}
+
+/**
+ * App Marketplace
+ * Available apps from the OpenMeter Marketplace.
+ */
+export class AppMarketplace {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * List available apps
+   * @param query - The query parameters
+   * @param signal - An optional abort signal
+   * @returns The apps
+   */
+  public async list(
+    query?: operations['listMarketplaceListings']['parameters']['query'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/marketplace/listings', {
+      params: { query },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get details for a listing
+   * @param type - The type of the listing
+   * @param signal - An optional abort signal
+   * @returns The listing
+   */
+  public async get(
+    type: operations['getMarketplaceListing']['parameters']['path']['type'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/marketplace/listings/{type}', {
+      params: { path: { type } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Install an app via OAuth. Returns a URL to start the OAuth 2.0 flow.
+   * @param type - The type of the listing
+   * @param signal - An optional abort signal
+   * @returns The OAuth2 install URL
+   */
+  public async getOauth2InstallUrl(
+    type: operations['marketplaceOAuth2InstallGetURL']['parameters']['path']['type'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET(
+      '/api/v1/marketplace/listings/{type}/install/oauth2',
+      {
+        params: { path: { type } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Authorize OAuth2 code. Verifies the OAuth code and exchanges it for a token and refresh token
+   * @param type - The type of the listing
+   * @param signal - An optional abort signal
+   * @returns The authorization URL
+   */
+  public async authorizeOauth2(
+    type: operations['marketplaceOAuth2InstallAuthorize']['parameters']['path']['type'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET(
+      '/api/v1/marketplace/listings/{type}/install/oauth2/authorize',
+      {
+        params: { path: { type } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Install an app via API key.
+   * @param type - The type of the listing
+   * @param signal - An optional abort signal
+   * @returns The installation
+   */
+  public async installWithAPIKey(
+    type: operations['marketplaceAppAPIKeyInstall']['parameters']['path']['type'],
+    body: operations['marketplaceAppAPIKeyInstall']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/marketplace/listings/{type}/install/apikey',
+      {
+        body,
+        params: { path: { type } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+}
+
+/**
+ * Stripe App
+ */
+export class AppStripe {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * Create a checkout session
+   * @param body - The body of the request
+   * @param signal - An optional abort signal
+   * @returns The checkout session
+   */
+  public async createCheckoutSession(
+    body: CreateStripeCheckoutSessionRequest,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST('/api/v1/stripe/checkout/sessions', {
+      body,
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Update Stripe API key
+   * @param id - The ID of the app
+   * @param body - The API key data
+   * @param options - The request options
+   * @returns The updated API key
+   * @deprecated
+   */
+  public async updateApiKey(
+    id: string,
+    body: operations['updateStripeAPIKey']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT('/api/v1/apps/{id}/stripe/api-key', {
+      body,
+      params: { path: { id } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+}
+
+/**
+ * Custom Invoicing App
+ */
+export class AppCustomInvoicing {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * Submit draft synchronization results
+   * @param invoiceId - The ID of the invoice
+   * @param body - The body of the request
+   * @param options - The request options
+   * @returns The synchronization result
+   */
+  public async draftSynchronized(
+    invoiceId: string,
+    body: operations['appCustomInvoicingDraftSynchronized']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/apps/custom-invoicing/{invoiceId}/draft/synchronized',
+      {
+        body,
+        params: { path: { invoiceId } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Submit issuing synchronization results
+   * @param invoiceId - The ID of the invoice
+   * @param body - The body of the request
+   * @param options - The request options
+   * @returns The synchronization result
+   */
+  public async issuingSynchronized(
+    invoiceId: string,
+    body: operations['appCustomInvoicingIssuingSynchronized']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/apps/custom-invoicing/{invoiceId}/issuing/synchronized',
+      {
+        body,
+        params: { path: { invoiceId } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Update payment status
+   * @param invoiceId - The ID of the invoice
+   * @param body - The body of the request
+   * @param options - The request options
+   * @returns The payment status update result
+   */
+  public async updatePaymentStatus(
+    invoiceId: string,
+    body: operations['appCustomInvoicingUpdatePaymentStatus']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/apps/custom-invoicing/{invoiceId}/payment/status',
+      {
+        body,
+        params: { path: { invoiceId } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+}

api/client/javascript/src/client/billing.ts

@@ -0,0 +1,525 @@
+import type { Client } from 'openapi-fetch'
+import type { RequestOptions } from './common.js'
+import type {
+  BillingProfileCreate,
+  BillingProfileCustomerOverrideCreate,
+  BillingProfileReplaceUpdateWithWorkflow,
+  InvoicePendingLineCreateInput,
+  InvoiceReplaceUpdate,
+  InvoiceSimulationInput,
+  operations,
+  paths,
+  VoidInvoiceActionInput,
+} from './schemas.js'
+import { transformResponse } from './utils.js'
+/**
+ * Billing
+ */
+export class Billing {
+  public profiles: BillingProfiles
+  public invoices: BillingInvoices
+  public customers: BillingCustomers
+
+  constructor(private client: Client<paths, `${string}/${string}`>) {
+    this.profiles = new BillingProfiles(this.client)
+    this.invoices = new BillingInvoices(this.client)
+    this.customers = new BillingCustomers(this.client)
+  }
+}
+
+/**
+ * Billing Profiles
+ */
+export class BillingProfiles {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * Create a billing profile
+   * @param billingProfile - The billing profile to create
+   * @param signal - An optional abort signal
+   * @returns The created billing profile
+   */
+  public async create(
+    billingProfile: BillingProfileCreate,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST('/api/v1/billing/profiles', {
+      body: billingProfile,
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get a billing profile by ID
+   * @param id - The ID of the billing profile to get
+   * @param signal - An optional abort signal
+   * @returns The billing profile
+   */
+  public async get(
+    id: operations['getBillingProfile']['parameters']['path']['id'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/billing/profiles/{id}', {
+      params: {
+        path: { id },
+      },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * List billing profiles
+   * @param query - The query parameters
+   * @param signal - An optional abort signal
+   * @returns The billing profiles
+   */
+  public async list(
+    query?: operations['listBillingProfiles']['parameters']['query'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/billing/profiles', {
+      params: {
+        query,
+      },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Update a billing profile
+   * @param id - The ID of the billing profile to update
+   * @param billingProfile - The billing profile to update
+   * @param signal - An optional abort signal
+   * @returns The updated billing profile
+   */
+  public async update(
+    id: operations['updateBillingProfile']['parameters']['path']['id'],
+    billingProfile: BillingProfileReplaceUpdateWithWorkflow,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT('/api/v1/billing/profiles/{id}', {
+      body: billingProfile,
+      params: {
+        path: { id },
+      },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Delete a billing profile
+   * @param id - The ID of the billing profile to delete
+   * @param options - The request options
+   * @returns The deleted billing profile
+   */
+  public async delete(
+    id: operations['deleteBillingProfile']['parameters']['path']['id'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.DELETE('/api/v1/billing/profiles/{id}', {
+      params: {
+        path: { id },
+      },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+}
+
+/**
+ * Billing Invoices
+ */
+export class BillingInvoices {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * List invoices
+   * @param query - The query parameters
+   * @param signal - An optional abort signal
+   * @returns The invoices
+   */
+  public async list(
+    query?: operations['listInvoices']['parameters']['query'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/billing/invoices', {
+      params: {
+        query,
+      },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get an invoice by ID
+   * @param id - The ID of the invoice to get
+   * @param signal - An optional abort signal
+   * @returns The invoice
+   */
+  public async get(
+    id: operations['getInvoice']['parameters']['path']['invoiceId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/billing/invoices/{invoiceId}', {
+      params: {
+        path: { invoiceId: id },
+      },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Update an invoice
+   * @description Only invoices in draft or earlier status can be updated.
+   * @param id - The ID of the invoice to update
+   * @param invoice - The invoice to update
+   * @param signal - An optional abort signal
+   * @returns The updated invoice
+   */
+  public async update(
+    id: operations['updateInvoice']['parameters']['path']['invoiceId'],
+    invoice: InvoiceReplaceUpdate,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT('/api/v1/billing/invoices/{invoiceId}', {
+      body: invoice,
+      params: { path: { invoiceId: id } },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Delete an invoice
+   * @description Only invoices that are in the draft (or earlier) status can be deleted.
+   * @param id - The ID of the invoice to delete
+   * @param options - The request options
+   * @returns The deleted invoice
+   */
+  public async delete(
+    id: operations['deleteInvoice']['parameters']['path']['invoiceId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.DELETE(
+      '/api/v1/billing/invoices/{invoiceId}',
+      {
+        params: { path: { invoiceId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Advance the invoice to the next status
+   * @description The call doesn't "approve the invoice", it only advances the invoice to the next status if the transition would be automatic. The action can be called when the invoice's statusDetails' actions field contain the "advance" action.
+   * @param id - The ID of the invoice to advance
+   * @param signal - An optional abort signal
+   * @returns The advanced invoice
+   */
+  public async advance(
+    id: operations['advanceInvoiceAction']['parameters']['path']['invoiceId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/billing/invoices/{invoiceId}/advance',
+      {
+        params: { path: { invoiceId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Approve an invoice
+   * @description This call instantly sends the invoice to the customer using the configured billing profile app.
+   * @param id - The ID of the invoice to approve
+   * @param signal - An optional abort signal
+   * @returns The approved invoice
+   */
+  public async approve(
+    id: operations['approveInvoiceAction']['parameters']['path']['invoiceId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/billing/invoices/{invoiceId}/approve',
+      {
+        params: { path: { invoiceId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Retry advancing the invoice after a failed attempt.
+   * @param id - The ID of the invoice to retry
+   * @param signal - An optional abort signal
+   * @returns The retried invoice
+   */
+  public async retry(
+    id: operations['retryInvoiceAction']['parameters']['path']['invoiceId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/billing/invoices/{invoiceId}/retry',
+      {
+        params: { path: { invoiceId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Void an invoice
+   * @description Void an invoice
+   *
+   *     Only invoices that have been alread issued can be voided.
+   * @param id - The ID of the invoice to void
+   * @param signal - An optional abort signal
+   * @returns The voided invoice
+   */
+  public async void(
+    id: operations['voidInvoiceAction']['parameters']['path']['invoiceId'],
+    body: VoidInvoiceActionInput,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/billing/invoices/{invoiceId}/void',
+      {
+        body,
+        params: { path: { invoiceId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Recalculate an invoice's tax amounts
+   * @param id - The ID of the invoice to recalculate
+   * @param signal - An optional abort signal
+   * @returns The recalculated invoice
+   */
+  public async recalculateTax(
+    id: operations['recalculateInvoiceTaxAction']['parameters']['path']['invoiceId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/billing/invoices/{invoiceId}/taxes/recalculate',
+      {
+        params: { path: { invoiceId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Snapshot invoice line item quantities
+   * @description Snapshot the quantities of the invoice line items. This is useful for invoices that have usage-based line items.
+   * @param id - The ID of the invoice to snapshot
+   * @param signal - An optional abort signal
+   * @returns The invoice with snapshotted quantities
+   */
+  public async snapshotQuantities(
+    id: operations['snapshotQuantitiesInvoiceAction']['parameters']['path']['invoiceId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/billing/invoices/{invoiceId}/snapshot-quantities',
+      {
+        params: { path: { invoiceId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Simulate an invoice for a customer
+   * @param id - The ID of the customer to simulate the invoice for
+   * @param signal - An optional abort signal
+   * @returns The simulated invoice
+   */
+  public async simulate(
+    id: operations['simulateInvoice']['parameters']['path']['customerId'],
+    body: InvoiceSimulationInput,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/billing/customers/{customerId}/invoices/simulate',
+      {
+        body,
+        params: { path: { customerId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Create pending line items
+   * @description Create new pending line items (charges).
+   *     This call is used to create a new pending line item for the customer if required a new
+   *     gathering invoice will be created.
+   *
+   *     A new invoice will be created if:
+   *     - there is no invoice in gathering state
+   *     - the currency of the line item doesn't match the currency of any invoices in gathering state
+   * @param customerId - The ID of the customer to create the line items for
+   * @param body - The line items to create
+   * @param signal - An optional abort signal
+   * @returns The created line items
+   */
+  public async createLineItems(
+    customerId: operations['createPendingInvoiceLine']['parameters']['path']['customerId'],
+    body: InvoicePendingLineCreateInput,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/billing/customers/{customerId}/invoices/pending-lines',
+      {
+        body,
+        params: { path: { customerId } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Invoice a customer based on the pending line items
+   * @description Create a new invoice from the pending line items. This should only be called if for some reason we need to invoice a customer outside of the normal billing cycle.
+   * @param body - The invoice data
+   * @param options - The request options
+   * @returns The created invoices
+   */
+  public async invoicePendingLines(
+    body: operations['invoicePendingLinesAction']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST('/api/v1/billing/invoices/invoice', {
+      body,
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+}
+
+/**
+ * Billing Customer Invoices and Overrides
+ */
+export class BillingCustomers {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * Create or update a customer override
+   * @param id - The ID of the customer to create the override for
+   * @param body - The customer override to create
+   * @param signal - An optional abort signal
+   * @returns The created customer override
+   */
+  public async createOverride(
+    id: operations['upsertBillingProfileCustomerOverride']['parameters']['path']['customerId'],
+    body: BillingProfileCustomerOverrideCreate,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT(
+      '/api/v1/billing/customers/{customerId}',
+      {
+        body,
+        params: { path: { customerId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get a customer override
+   * @param id - The ID of the customer to get the override for
+   * @param signal - An optional abort signal
+   * @returns The customer override
+   */
+  public async getOverride(
+    id: operations['getBillingProfileCustomerOverride']['parameters']['path']['customerId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET(
+      '/api/v1/billing/customers/{customerId}',
+      {
+        params: { path: { customerId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * List customer overrides
+   * @param query - The query parameters
+   * @param signal - An optional abort signal
+   * @returns The customer overrides
+   */
+  public async listOverrides(
+    query?: operations['listBillingProfileCustomerOverrides']['parameters']['query'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/billing/customers', {
+      params: { query },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Delete a customer override
+   * @param id - The ID of the customer to delete the override for
+   * @param signal - An optional abort signal
+   * @returns The deleted customer override
+   */
+  public async deleteOverride(
+    id: operations['deleteBillingProfileCustomerOverride']['parameters']['path']['customerId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.DELETE(
+      '/api/v1/billing/customers/{customerId}',
+      {
+        params: { path: { customerId: id } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+}

api/client/javascript/src/client/common.ts

@@ -0,0 +1,66 @@
+import type { UnexpectedProblemResponse } from './schemas.js'
+
+/**
+ * Request options
+ */
+export type RequestOptions = Pick<RequestInit, 'signal'>
+
+/**
+ * An error that occurred during an HTTP request
+ */
+export class HTTPError extends Error {
+  public name = 'HTTPError'
+  public client = 'OpenMeter'
+
+  constructor(
+    public message: string,
+    public type: string,
+    public title: string,
+    public status: number,
+    public url: string,
+    protected __raw?: Record<string, unknown>,
+  ) {
+    super(message)
+  }
+
+  static fromResponse(resp: {
+    response: Response
+    error?: UnexpectedProblemResponse
+  }): HTTPError {
+    if (
+      resp.response.headers.get('Content-Type') ===
+        'application/problem+json' &&
+      resp.error
+    ) {
+      return new HTTPError(
+        `Request failed (${resp.response.url}) [${resp.response.status}]: ${resp.error.detail}`,
+        resp.error.type,
+        resp.error.title,
+        resp.error.status ?? resp.response.status,
+        resp.response.url,
+        resp.error,
+      )
+    }
+
+    return new HTTPError(
+      `Request failed (${resp.response.url}) [${resp.response.status}]: ${resp.response.statusText}`,
+      resp.response.statusText,
+      resp.response.statusText,
+      resp.response.status,
+      resp.response.url,
+    )
+  }
+
+  getField(key: string) {
+    return this.__raw?.[key]
+  }
+}
+
+/**
+ * Check if an error is an HTTPError
+ * @param error - The error to check
+ * @returns Whether the error is an HTTPError
+ */
+export function isHTTPError(error: unknown): error is HTTPError {
+  return error instanceof HTTPError
+}

api/client/javascript/src/client/customers.ts

@@ -0,0 +1,672 @@
+import type { Client } from 'openapi-fetch'
+import type { RequestOptions } from './common.js'
+import type {
+  CreateStripeCustomerPortalSessionParams,
+  CustomerAppData,
+  CustomerCreate,
+  CustomerReplaceUpdate,
+  operations,
+  paths,
+  StripeCustomerAppDataBase,
+} from './schemas.js'
+import { transformResponse } from './utils.js'
+
+/**
+ * Customers
+ * Manage customer subscription lifecycles and plan assignments.
+ */
+export class Customers {
+  public apps: CustomerApps
+  public entitlementsV1: CustomerEntitlements
+  public entitlements: CustomerEntitlementsV2
+  public stripe: CustomerStripe
+
+  constructor(private client: Client<paths, `${string}/${string}`>) {
+    this.apps = new CustomerApps(client)
+    this.entitlementsV1 = new CustomerEntitlements(client)
+    this.entitlements = new CustomerEntitlementsV2(client)
+    this.stripe = new CustomerStripe(client)
+  }
+
+  /**
+   * Create a customer
+   * @param customer - The customer to create
+   * @param signal - An optional abort signal
+   * @returns The created customer
+   */
+  public async create(customer: CustomerCreate, options?: RequestOptions) {
+    const resp = await this.client.POST('/api/v1/customers', {
+      body: customer,
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get a customer by ID
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param signal - An optional abort signal
+   * @returns The customer
+   */
+  public async get(
+    customerIdOrKey: operations['getCustomer']['parameters']['path']['customerIdOrKey'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/customers/{customerIdOrKey}', {
+      params: {
+        path: {
+          customerIdOrKey,
+        },
+      },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Update a customer
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param customer - The customer to update
+   * @param signal - An optional abort signal
+   * @returns The updated customer
+   */
+  public async update(
+    customerIdOrKey: operations['updateCustomer']['parameters']['path']['customerIdOrKey'],
+    customer: CustomerReplaceUpdate,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT('/api/v1/customers/{customerIdOrKey}', {
+      body: customer,
+      params: {
+        path: {
+          customerIdOrKey,
+        },
+      },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Delete a customer
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param signal - An optional abort signal
+   * @returns The deleted customer
+   */
+  public async delete(
+    customerIdOrKey: operations['deleteCustomer']['parameters']['path']['customerIdOrKey'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.DELETE(
+      '/api/v1/customers/{customerIdOrKey}',
+      {
+        params: {
+          path: {
+            customerIdOrKey,
+          },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * List customers
+   * @param signal - An optional abort signal
+   * @returns The list of customers
+   */
+  public async list(
+    query?: operations['listCustomers']['parameters']['query'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET('/api/v1/customers', {
+      params: {
+        query,
+      },
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get customer access
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param options - Optional request options
+   * @returns The customer access information
+   */
+  public async getAccess(
+    customerIdOrKey: operations['getCustomerAccess']['parameters']['path']['customerIdOrKey'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET(
+      '/api/v1/customers/{customerIdOrKey}/access',
+      {
+        params: {
+          path: {
+            customerIdOrKey,
+          },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * List customer subscriptions
+   * @param customerIdOrKey - The ID or key of the customer
+   * @param query - The query parameters
+   * @param signal - An optional abort signal
+   * @returns The list of customer subscriptions
+   */
+  public async listSubscriptions(
+    customerIdOrKey: operations['listCustomerSubscriptions']['parameters']['path']['customerIdOrKey'],
+    query?: operations['listCustomerSubscriptions']['parameters']['query'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET(
+      '/api/v1/customers/{customerIdOrKey}/subscriptions',
+      {
+        params: { path: { customerIdOrKey }, query },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+}
+
+/**
+ * Customer Apps
+ * Manage customer apps.
+ */
+export class CustomerApps {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * Upsert customer app data
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param appData - The app data to upsert
+   * @param signal - An optional abort signal
+   * @returns The upserted app data
+   */
+  public async upsert(
+    customerIdOrKey: operations['upsertCustomerAppData']['parameters']['path']['customerIdOrKey'],
+    appData: CustomerAppData[],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT(
+      '/api/v1/customers/{customerIdOrKey}/apps',
+      {
+        body: appData,
+        params: {
+          path: {
+            customerIdOrKey,
+          },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * List customer app data
+   * @param customerIdOrKey - The ID or key of the customer
+   * @param query - The query parameters
+   * @param signal - An optional abort signal
+   * @returns The list of customer app data
+   */
+  public async list(
+    customerIdOrKey: operations['listCustomerAppData']['parameters']['path']['customerIdOrKey'],
+    query?: operations['listCustomerAppData']['parameters']['query'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET(
+      '/api/v1/customers/{customerIdOrKey}/apps',
+      {
+        params: {
+          path: { customerIdOrKey },
+          query,
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Delete customer app data
+   * @param customerIdOrKey - The ID or key of the customer
+   * @param appId - The ID of the app
+   * @param signal - An optional abort signal
+   * @returns The deleted customer app data
+   */
+  public async delete(
+    customerIdOrKey: operations['deleteCustomerAppData']['parameters']['path']['customerIdOrKey'],
+    appId: operations['deleteCustomerAppData']['parameters']['path']['appId'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.DELETE(
+      '/api/v1/customers/{customerIdOrKey}/apps/{appId}',
+      {
+        params: { path: { appId, customerIdOrKey } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+}
+
+/**
+ * Customer Stripe
+ * Manage customer Stripe data.
+ */
+export class CustomerStripe {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * Upsert customer stripe app data
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param appData - The app data to upsert
+   * @param signal - An optional abort signal
+   * @returns The upserted customer stripe app data
+   */
+  public async upsert(
+    customerIdOrKey: operations['upsertCustomerStripeAppData']['parameters']['path']['customerIdOrKey'],
+    stripeAppData: StripeCustomerAppDataBase,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT(
+      '/api/v1/customers/{customerIdOrKey}/stripe',
+      {
+        body: stripeAppData,
+        params: {
+          path: {
+            customerIdOrKey,
+          },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get customer stripe app data
+   * @param customerIdOrKey - The ID or key of the customer
+   * @param query - The query parameters
+   * @param signal - An optional abort signal
+   * @returns The customer stripe app data
+   */
+  public async get(
+    customerIdOrKey: operations['getCustomerStripeAppData']['parameters']['path']['customerIdOrKey'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET(
+      '/api/v1/customers/{customerIdOrKey}/stripe',
+      {
+        params: {
+          path: { customerIdOrKey },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Create a Stripe customer portal session
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param params - The parameters for creating a Stripe customer portal session
+   * @param signal - An optional abort signal
+   * @returns The Stripe customer portal session
+   */
+  public async createPortalSession(
+    customerIdOrKey: operations['createCustomerStripePortalSession']['parameters']['path']['customerIdOrKey'],
+    params: CreateStripeCustomerPortalSessionParams,
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v1/customers/{customerIdOrKey}/stripe/portal',
+      {
+        body: params,
+        params: {
+          path: {
+            customerIdOrKey,
+          },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+}
+
+/**
+ * Customer Entitlements
+ */
+export class CustomerEntitlements {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * Get the value of an entitlement for a customer
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param featureKey - The key of the feature
+   * @param signal - An optional abort signal
+   * @returns The value of the entitlement
+   */
+  public async value(
+    customerIdOrKey: operations['getCustomerEntitlementValue']['parameters']['path']['customerIdOrKey'],
+    featureKey: operations['getCustomerEntitlementValue']['parameters']['path']['featureKey'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET(
+      '/api/v1/customers/{customerIdOrKey}/entitlements/{featureKey}/value',
+      {
+        params: { path: { customerIdOrKey, featureKey } },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+}
+
+/**
+ * Customer Entitlements V2
+ */
+export class CustomerEntitlementsV2 {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * List all entitlements for a customer
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param options - Request options including query parameters
+   * @returns List of customer entitlements
+   */
+  public async list(
+    customerIdOrKey: operations['listCustomerEntitlementsV2']['parameters']['path']['customerIdOrKey'],
+    options?: RequestOptions & {
+      query?: operations['listCustomerEntitlementsV2']['parameters']['query']
+    },
+  ) {
+    const resp = await this.client.GET(
+      '/api/v2/customers/{customerIdOrKey}/entitlements',
+      {
+        params: {
+          path: { customerIdOrKey },
+          query: options?.query,
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Create a customer entitlement
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param entitlement - The entitlement data to create
+   * @param options - Request options
+   * @returns The created entitlement
+   */
+  public async create(
+    customerIdOrKey: operations['createCustomerEntitlementV2']['parameters']['path']['customerIdOrKey'],
+    entitlement: operations['createCustomerEntitlementV2']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v2/customers/{customerIdOrKey}/entitlements',
+      {
+        body: entitlement,
+        params: {
+          path: { customerIdOrKey },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get a specific customer entitlement
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param entitlementIdOrFeatureKey - The ID or feature key of the entitlement
+   * @param options - Request options
+   * @returns The entitlement
+   */
+  public async get(
+    customerIdOrKey: operations['getCustomerEntitlementV2']['parameters']['path']['customerIdOrKey'],
+    entitlementIdOrFeatureKey: operations['getCustomerEntitlementV2']['parameters']['path']['entitlementIdOrFeatureKey'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.GET(
+      '/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}',
+      {
+        params: {
+          path: { customerIdOrKey, entitlementIdOrFeatureKey },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Delete a customer entitlement
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param entitlementIdOrFeatureKey - The ID or feature key of the entitlement
+   * @param options - Request options
+   * @returns The deletion response
+   */
+  public async delete(
+    customerIdOrKey: operations['deleteCustomerEntitlementV2']['parameters']['path']['customerIdOrKey'],
+    entitlementIdOrFeatureKey: operations['deleteCustomerEntitlementV2']['parameters']['path']['entitlementIdOrFeatureKey'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.DELETE(
+      '/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}',
+      {
+        params: {
+          path: { customerIdOrKey, entitlementIdOrFeatureKey },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Override a customer entitlement
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param entitlementIdOrFeatureKey - The ID or feature key of the entitlement
+   * @param entitlement - The new entitlement data
+   * @param options - Request options
+   * @returns The overridden entitlement
+   */
+  public async override(
+    customerIdOrKey: operations['overrideCustomerEntitlementV2']['parameters']['path']['customerIdOrKey'],
+    entitlementIdOrFeatureKey: operations['overrideCustomerEntitlementV2']['parameters']['path']['entitlementIdOrFeatureKey'],
+    entitlement: operations['overrideCustomerEntitlementV2']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.PUT(
+      '/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/override',
+      {
+        body: entitlement,
+        params: {
+          path: { customerIdOrKey, entitlementIdOrFeatureKey },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * List grants for a customer entitlement
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param entitlementIdOrFeatureKey - The ID or feature key of the entitlement
+   * @param options - Request options including query parameters
+   * @returns List of entitlement grants
+   */
+  public async listGrants(
+    customerIdOrKey: operations['listCustomerEntitlementGrantsV2']['parameters']['path']['customerIdOrKey'],
+    entitlementIdOrFeatureKey: operations['listCustomerEntitlementGrantsV2']['parameters']['path']['entitlementIdOrFeatureKey'],
+    options?: RequestOptions & {
+      query?: operations['listCustomerEntitlementGrantsV2']['parameters']['query']
+    },
+  ) {
+    const resp = await this.client.GET(
+      '/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/grants',
+      {
+        params: {
+          path: { customerIdOrKey, entitlementIdOrFeatureKey },
+          query: options?.query,
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Create a grant for a customer entitlement
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param entitlementIdOrFeatureKey - The ID or feature key of the entitlement
+   * @param grant - The grant data to create
+   * @param options - Request options
+   * @returns The created grant
+   */
+  public async createGrant(
+    customerIdOrKey: operations['createCustomerEntitlementGrantV2']['parameters']['path']['customerIdOrKey'],
+    entitlementIdOrFeatureKey: operations['createCustomerEntitlementGrantV2']['parameters']['path']['entitlementIdOrFeatureKey'],
+    grant: operations['createCustomerEntitlementGrantV2']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/grants',
+      {
+        body: grant,
+        params: {
+          path: { customerIdOrKey, entitlementIdOrFeatureKey },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get the value of a customer entitlement
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param entitlementIdOrFeatureKey - The ID or feature key of the entitlement
+   * @param options - Request options including query parameters
+   * @returns The entitlement value
+   */
+  public async value(
+    customerIdOrKey: operations['getCustomerEntitlementValueV2']['parameters']['path']['customerIdOrKey'],
+    entitlementIdOrFeatureKey: operations['getCustomerEntitlementValueV2']['parameters']['path']['entitlementIdOrFeatureKey'],
+    options?: RequestOptions & {
+      query?: operations['getCustomerEntitlementValueV2']['parameters']['query']
+    },
+  ) {
+    const resp = await this.client.GET(
+      '/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/value',
+      {
+        params: {
+          path: { customerIdOrKey, entitlementIdOrFeatureKey },
+          query: options?.query,
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Get the history of a customer entitlement
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param entitlementIdOrFeatureKey - The ID or feature key of the entitlement
+   * @param windowSize - The window size for the history
+   * @param options - Request options including query parameters
+   * @returns The entitlement history
+   */
+  public async history(
+    customerIdOrKey: operations['getCustomerEntitlementHistoryV2']['parameters']['path']['customerIdOrKey'],
+    entitlementIdOrFeatureKey: operations['getCustomerEntitlementHistoryV2']['parameters']['path']['entitlementIdOrFeatureKey'],
+    windowSize: operations['getCustomerEntitlementHistoryV2']['parameters']['query']['windowSize'],
+    options?: RequestOptions & {
+      query?: Omit<
+        operations['getCustomerEntitlementHistoryV2']['parameters']['query'],
+        'windowSize'
+      >
+    },
+  ) {
+    const resp = await this.client.GET(
+      '/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/history',
+      {
+        params: {
+          path: { customerIdOrKey, entitlementIdOrFeatureKey },
+          query: {
+            windowSize,
+            ...options?.query,
+          },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+
+  /**
+   * Reset the usage of a customer entitlement
+   * @param customerIdOrKey - The ID or Key of the customer
+   * @param entitlementIdOrFeatureKey - The ID or feature key of the entitlement
+   * @param reset - The reset data
+   * @param options - Request options
+   * @returns The reset response
+   */
+  public async resetUsage(
+    customerIdOrKey: operations['resetCustomerEntitlementUsageV2']['parameters']['path']['customerIdOrKey'],
+    entitlementIdOrFeatureKey: operations['resetCustomerEntitlementUsageV2']['parameters']['path']['entitlementIdOrFeatureKey'],
+    reset: operations['resetCustomerEntitlementUsageV2']['requestBody']['content']['application/json'],
+    options?: RequestOptions,
+  ) {
+    const resp = await this.client.POST(
+      '/api/v2/customers/{customerIdOrKey}/entitlements/{entitlementIdOrFeatureKey}/reset',
+      {
+        body: reset,
+        params: {
+          path: { customerIdOrKey, entitlementIdOrFeatureKey },
+        },
+        ...options,
+      },
+    )
+
+    return transformResponse(resp)
+  }
+}

api/client/javascript/src/client/debug.ts

@@ -0,0 +1,25 @@
+import type { Client } from 'openapi-fetch'
+import type { RequestOptions } from './common.js'
+import type { paths } from './schemas.js'
+import { transformResponse } from './utils.js'
+
+/**
+ * Debug utilities for OpenMeter
+ */
+export class Debug {
+  constructor(private client: Client<paths, `${string}/${string}`>) {}
+
+  /**
+   * Get event metrics
+   * @description Returns debug metrics (in OpenMetrics format) like the number of ingested events since mindnight UTC.
+   * @param options - The request options
+   * @returns The debug metrics
+   */
+  public async getMetrics(options?: RequestOptions) {
+    const resp = await this.client.GET('/api/v1/debug/metrics', {
+      ...options,
+    })
+
+    return transformResponse(resp)
+  }
+}