@dainamite/billing 0.17.0

package/dist/modules/billing/api/runs/route.js

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { makeCrudRoute } from "@open-mercato/shared/lib/crud/factory";
+import { withScopedPayload } from "@open-mercato/shared/lib/api/scoped";
+import { resolveTranslations } from "@open-mercato/shared/lib/i18n/server";
+import { BillRun } from "../../data/entities.js";
+import { billingEntityIds } from "../../data/entityIds.js";
+import {
+  billingRunListQuerySchema,
+  billingRunTriggerSchema
+} from "../../data/validators.js";
+import { createBillingCrudOpenApi, createPagedListResponseSchema } from "../openapi.js";
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ["billing.run.view"] },
+  POST: { requireAuth: true, requireFeatures: ["billing.run.trigger"] }
+};
+const metadata = routeMetadata;
+const billRunListItemSchema = z.object({
+  id: z.string().uuid(),
+  triggered_by: z.string(),
+  parent_run_id: z.string().uuid().nullable(),
+  dry_run: z.boolean(),
+  test_mode: z.boolean(),
+  catch_up: z.boolean(),
+  scoped_account_ids: z.array(z.string().uuid()).nullable(),
+  as_of_date: z.string(),
+  started_at: z.string().nullable(),
+  finished_at: z.string().nullable(),
+  status: z.string(),
+  summary: z.record(z.string(), z.unknown()).nullable(),
+  organization_id: z.string().uuid(),
+  tenant_id: z.string().uuid(),
+  created_at: z.string(),
+  updated_at: z.string()
+});
+const triggerResponseSchema = z.object({
+  billRunId: z.string().uuid(),
+  status: z.string(),
+  outcomesCount: z.number().int().nonnegative()
+});
+const rawBodySchema = z.object({}).passthrough();
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillRun,
+    idField: "id",
+    orgField: "organizationId",
+    tenantField: "tenantId",
+    softDeleteField: "deletedAt"
+  },
+  list: {
+    schema: billingRunListQuerySchema,
+    entityId: billingEntityIds.run,
+    fields: [
+      "id",
+      "triggered_by",
+      "parent_run_id",
+      "dry_run",
+      "test_mode",
+      "catch_up",
+      "scoped_account_ids",
+      "as_of_date",
+      "started_at",
+      "finished_at",
+      "status",
+      "summary",
+      "organization_id",
+      "tenant_id",
+      "created_at",
+      "updated_at"
+    ],
+    sortFieldMap: {
+      startedAt: "started_at",
+      finishedAt: "finished_at",
+      asOfDate: "as_of_date",
+      createdAt: "created_at"
+    },
+    buildFilters: async (query) => {
+      const filters = {};
+      if (typeof query.id === "string" && query.id) {
+        filters.id = { $eq: query.id };
+      }
+      if (typeof query.search === "string" && /^[0-9a-fA-F-]{36}$/.test(query.search.trim())) {
+        filters.id = { $eq: query.search.trim() };
+      }
+      if (typeof query.status === "string") filters.status = { $eq: query.status };
+      if (typeof query.triggeredBy === "string") filters.triggered_by = { $eq: query.triggeredBy };
+      if (typeof query.parentRunId === "string") filters.parent_run_id = { $eq: query.parentRunId };
+      if (query.asOfDateFrom instanceof Date) {
+        filters.as_of_date = Object.assign(
+          filters.as_of_date ?? {},
+          { $gte: query.asOfDateFrom }
+        );
+      }
+      if (query.asOfDateTo instanceof Date) {
+        filters.as_of_date = Object.assign(
+          filters.as_of_date ?? {},
+          { $lte: query.asOfDateTo }
+        );
+      }
+      return filters;
+    }
+  },
+  actions: {
+    create: {
+      commandId: "billing.runs.trigger",
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations();
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate);
+        return billingRunTriggerSchema.parse(scoped);
+      },
+      response: ({ result }) => ({
+        billRunId: result?.billRunId ?? null,
+        status: result?.status ?? null,
+        outcomesCount: result?.outcomesCount ?? 0
+      }),
+      status: 201
+    }
+    // Runs are append-only — no update / delete on this surface. A
+    // failed run is corrected by triggering a `retry-failed` (separate
+    // route).
+  }
+});
+const { POST } = crud;
+const GET = crud.GET;
+const openApi = createBillingCrudOpenApi({
+  resourceName: "BillRun",
+  pluralName: "BillRuns",
+  querySchema: billingRunListQuerySchema,
+  listResponseSchema: createPagedListResponseSchema(billRunListItemSchema),
+  create: {
+    schema: billingRunTriggerSchema,
+    responseSchema: triggerResponseSchema,
+    description: "Triggers a Bill Run. `mode=real` (default) persists drafts and advances state; `mode=test` persists test-flagged drafts without advancing state; `mode=dry` computes everything in memory and persists nothing. Returns HTTP 409 (`billing.run.lock_busy`) when another run is in flight for the same tenant."
+  }
+});
+export {
+  GET,
+  POST,
+  metadata,
+  openApi
+};
+//# sourceMappingURL=route.js.map

package/dist/modules/billing/api/runs/route.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/modules/billing/api/runs/route.ts"],
+  "sourcesContent": ["import { z } from 'zod'\nimport { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'\nimport { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'\nimport { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'\nimport { BillRun } from '../../data/entities'\nimport { billingEntityIds } from '../../data/entityIds'\nimport {\n  billingRunListQuerySchema,\n  billingRunTriggerSchema,\n} from '../../data/validators'\nimport { createBillingCrudOpenApi, createPagedListResponseSchema } from '../openapi'\n\n/**\n * `/api/billing/runs` \u2014 GET (history list) + POST (manual trigger).\n *\n * The triggered-by enum gate:\n *   - `trigger` feature is required for `real` mode (which mutates\n *     production state).\n *   - `dry_run` feature alone is enough for `mode=dry` (finance auditor\n *     persona). The route-level RBAC check on POST requires `trigger`,\n *     so dry-run callers must hold both `dry_run` AND `trigger` here \u2014\n *     a deliberate tightening over what the spec persona table suggests.\n *\n *   If we ever want auditors to drive dry-runs without holding `trigger`,\n *   we split into two routes (POST `/runs` for real, POST `/runs/dry` for\n *   dry). Postponed until an operator actually asks.\n */\n\nconst routeMetadata = {\n  GET: { requireAuth: true, requireFeatures: ['billing.run.view'] },\n  POST: { requireAuth: true, requireFeatures: ['billing.run.trigger'] },\n}\n\nexport const metadata = routeMetadata\n\n// The list endpoint projects raw column names \u2014 snake_case.\nconst billRunListItemSchema = z.object({\n  id: z.string().uuid(),\n  triggered_by: z.string(),\n  parent_run_id: z.string().uuid().nullable(),\n  dry_run: z.boolean(),\n  test_mode: z.boolean(),\n  catch_up: z.boolean(),\n  scoped_account_ids: z.array(z.string().uuid()).nullable(),\n  as_of_date: z.string(),\n  started_at: z.string().nullable(),\n  finished_at: z.string().nullable(),\n  status: z.string(),\n  summary: z.record(z.string(), z.unknown()).nullable(),\n  organization_id: z.string().uuid(),\n  tenant_id: z.string().uuid(),\n  created_at: z.string(),\n  updated_at: z.string(),\n})\n\nconst triggerResponseSchema = z.object({\n  billRunId: z.string().uuid(),\n  status: z.string(),\n  outcomesCount: z.number().int().nonnegative(),\n})\n\nconst rawBodySchema = z.object({}).passthrough()\n\nconst crud = makeCrudRoute({\n  metadata: routeMetadata,\n  orm: {\n    entity: BillRun,\n    idField: 'id',\n    orgField: 'organizationId',\n    tenantField: 'tenantId',\n    softDeleteField: 'deletedAt',\n  },\n  list: {\n    schema: billingRunListQuerySchema,\n    entityId: billingEntityIds.run,\n    fields: [\n      'id',\n      'triggered_by',\n      'parent_run_id',\n      'dry_run',\n      'test_mode',\n      'catch_up',\n      'scoped_account_ids',\n      'as_of_date',\n      'started_at',\n      'finished_at',\n      'status',\n      'summary',\n      'organization_id',\n      'tenant_id',\n      'created_at',\n      'updated_at',\n    ],\n    sortFieldMap: {\n      startedAt: 'started_at',\n      finishedAt: 'finished_at',\n      asOfDate: 'as_of_date',\n      createdAt: 'created_at',\n    },\n    buildFilters: async (query) => {\n      const filters: Record<string, unknown> = {}\n      // `?id=<uuid>` narrows the list to one row \u2014 the detail page\n      // reads a single Bill Run through this filter.\n      if (typeof query.id === 'string' && query.id) {\n        filters.id = { $eq: query.id }\n      }\n      // Run ids are UUIDs \u2014 search matches a pasted id exactly.\n      if (typeof query.search === 'string' && /^[0-9a-fA-F-]{36}$/.test(query.search.trim())) {\n        filters.id = { $eq: query.search.trim() }\n      }\n      if (typeof query.status === 'string') filters.status = { $eq: query.status }\n      if (typeof query.triggeredBy === 'string') filters.triggered_by = { $eq: query.triggeredBy }\n      if (typeof query.parentRunId === 'string') filters.parent_run_id = { $eq: query.parentRunId }\n      if (query.asOfDateFrom instanceof Date) {\n        filters.as_of_date = Object.assign(\n          (filters.as_of_date as Record<string, unknown>) ?? {},\n          { $gte: query.asOfDateFrom },\n        )\n      }\n      if (query.asOfDateTo instanceof Date) {\n        filters.as_of_date = Object.assign(\n          (filters.as_of_date as Record<string, unknown>) ?? {},\n          { $lte: query.asOfDateTo },\n        )\n      }\n      return filters\n    },\n  },\n  actions: {\n    create: {\n      commandId: 'billing.runs.trigger',\n      schema: rawBodySchema,\n      mapInput: async ({ raw, ctx }) => {\n        const { translate } = await resolveTranslations()\n        const scoped = withScopedPayload(raw ?? {}, ctx, translate)\n        return billingRunTriggerSchema.parse(scoped)\n      },\n      response: ({ result }) => ({\n        billRunId: result?.billRunId ?? null,\n        status: result?.status ?? null,\n        outcomesCount: result?.outcomesCount ?? 0,\n      }),\n      status: 201,\n    },\n    // Runs are append-only \u2014 no update / delete on this surface. A\n    // failed run is corrected by triggering a `retry-failed` (separate\n    // route).\n  },\n})\n\nconst { POST } = crud\nexport { POST }\nexport const GET = crud.GET\n\nexport const openApi = createBillingCrudOpenApi({\n  resourceName: 'BillRun',\n  pluralName: 'BillRuns',\n  querySchema: billingRunListQuerySchema,\n  listResponseSchema: createPagedListResponseSchema(billRunListItemSchema),\n  create: {\n    schema: billingRunTriggerSchema,\n    responseSchema: triggerResponseSchema,\n    description:\n      'Triggers a Bill Run. `mode=real` (default) persists drafts and ' +\n      'advances state; `mode=test` persists test-flagged drafts without ' +\n      'advancing state; `mode=dry` computes everything in memory and ' +\n      'persists nothing. Returns HTTP 409 (`billing.run.lock_busy`) when ' +\n      'another run is in flight for the same tenant.',\n  },\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/billing/api/test-invoices/wipe/route.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { makeCrudRoute } from "@open-mercato/shared/lib/crud/factory";
+import { withScopedPayload } from "@open-mercato/shared/lib/api/scoped";
+import { resolveTranslations } from "@open-mercato/shared/lib/i18n/server";
+import { SalesInvoice } from "@open-mercato/core/modules/sales/data/entities";
+import { billingEntityIds } from "../../../data/entityIds.js";
+import { billingWipeTestInvoicesSchema } from "../../../data/validators.js";
+import { createBillingCrudOpenApi } from "../../openapi.js";
+const routeMetadata = {
+  POST: { requireAuth: true, requireFeatures: ["billing.run.trigger"] }
+};
+const metadata = routeMetadata;
+const wipeResponseSchema = z.object({
+  invoicesRemoved: z.number().int().nonnegative()
+});
+const rawBodySchema = z.object({}).passthrough();
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: SalesInvoice,
+    idField: "id",
+    orgField: "organizationId",
+    tenantField: "tenantId",
+    softDeleteField: "deletedAt"
+  },
+  list: {
+    schema: z.object({}).passthrough(),
+    entityId: billingEntityIds.draftInvoiceEdit,
+    fields: ["id"],
+    buildFilters: async () => ({})
+  },
+  actions: {
+    create: {
+      commandId: "billing.invoices.wipe_test",
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations();
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate);
+        return billingWipeTestInvoicesSchema.parse(scoped);
+      },
+      response: ({ result }) => ({
+        invoicesRemoved: result?.invoicesRemoved ?? 0
+      }),
+      status: 200
+    }
+  }
+});
+const POST = crud.POST;
+const openApi = createBillingCrudOpenApi({
+  resourceName: "BillingTestInvoiceWipe",
+  pluralName: "BillingTestInvoiceWipes",
+  querySchema: z.object({}).passthrough(),
+  listResponseSchema: z.object({ items: z.array(z.unknown()) }),
+  create: {
+    schema: billingWipeTestInvoicesSchema,
+    responseSchema: wipeResponseSchema,
+    description: "Hard-deletes test invoices (`metadata.test_run=true`) for the authenticated tenant. Pass `billRunId` to wipe only invoices from a specific test Bill Run. Returns the count removed. Test data should not pollute production history, so this is a hard delete, not a soft delete."
+  }
+});
+export {
+  POST,
+  metadata,
+  openApi
+};
+//# sourceMappingURL=route.js.map

package/dist/modules/billing/api/test-invoices/wipe/route.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../src/modules/billing/api/test-invoices/wipe/route.ts"],
+  "sourcesContent": ["import { z } from 'zod'\nimport { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'\nimport { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'\nimport { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'\nimport { SalesInvoice } from '@open-mercato/core/modules/sales/data/entities'\nimport { billingEntityIds } from '../../../data/entityIds'\nimport { billingWipeTestInvoicesSchema } from '../../../data/validators'\nimport { createBillingCrudOpenApi } from '../../openapi'\n\n/**\n * `POST /api/billing/test-invoices/wipe` \u2014 hard-delete invoices\n * flagged `metadata.test_run=true` for this tenant. Optionally\n * scoped to a `billRunId` so an operator can wipe a single test run\n * without nuking other test data.\n *\n * Modelled as POST (not DELETE) because the body carries the scope\n * fields and modern Next.js routers reject DELETE-with-body more\n * consistently than they accept it; keeping POST keeps the surface\n * uniform with the rest of the billing API.\n *\n * Gated by `billing.run.trigger` (test mode is part of the\n * \"operate Bill Runs\" toolkit). Phase 4c admin UI exposes this\n * behind a confirm dialog on the Bill Run detail page.\n */\n\nconst routeMetadata = {\n  POST: { requireAuth: true, requireFeatures: ['billing.run.trigger'] },\n}\n\nexport const metadata = routeMetadata\n\nconst wipeResponseSchema = z.object({\n  invoicesRemoved: z.number().int().nonnegative(),\n})\n\nconst rawBodySchema = z.object({}).passthrough()\n\nconst crud = makeCrudRoute({\n  metadata: routeMetadata,\n  orm: {\n    entity: SalesInvoice,\n    idField: 'id',\n    orgField: 'organizationId',\n    tenantField: 'tenantId',\n    softDeleteField: 'deletedAt',\n  },\n  list: {\n    schema: z.object({}).passthrough(),\n    entityId: billingEntityIds.draftInvoiceEdit,\n    fields: ['id'],\n    buildFilters: async () => ({}),\n  },\n  actions: {\n    create: {\n      commandId: 'billing.invoices.wipe_test',\n      schema: rawBodySchema,\n      mapInput: async ({ raw, ctx }) => {\n        const { translate } = await resolveTranslations()\n        const scoped = withScopedPayload(raw ?? {}, ctx, translate)\n        return billingWipeTestInvoicesSchema.parse(scoped)\n      },\n      response: ({ result }) => ({\n        invoicesRemoved: result?.invoicesRemoved ?? 0,\n      }),\n      status: 200,\n    },\n  },\n})\n\nexport const POST = crud.POST\n\nexport const openApi = createBillingCrudOpenApi({\n  resourceName: 'BillingTestInvoiceWipe',\n  pluralName: 'BillingTestInvoiceWipes',\n  querySchema: z.object({}).passthrough(),\n  listResponseSchema: z.object({ items: z.array(z.unknown()) }),\n  create: {\n    schema: billingWipeTestInvoicesSchema,\n    responseSchema: wipeResponseSchema,\n    description:\n      'Hard-deletes test invoices (`metadata.test_run=true`) for the ' +\n      'authenticated tenant. Pass `billRunId` to wipe only invoices ' +\n      'from a specific test Bill Run. Returns the count removed. ' +\n      'Test data should not pollute production history, so this is a ' +\n      'hard delete, not a soft delete.',\n  },\n})\n"],
+  "mappings": "AAAA,SAAS,SAAS;AAClB,SAAS,qBAAqB;AAC9B,SAAS,yBAAyB;AAClC,SAAS,2BAA2B;AACpC,SAAS,oBAAoB;AAC7B,SAAS,wBAAwB;AACjC,SAAS,qCAAqC;AAC9C,SAAS,gCAAgC;AAkBzC,MAAM,gBAAgB;AAAA,EACpB,MAAM,EAAE,aAAa,MAAM,iBAAiB,CAAC,qBAAqB,EAAE;AACtE;AAEO,MAAM,WAAW;AAExB,MAAM,qBAAqB,EAAE,OAAO;AAAA,EAClC,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY;AAChD,CAAC;AAED,MAAM,gBAAgB,EAAE,OAAO,CAAC,CAAC,EAAE,YAAY;AAE/C,MAAM,OAAO,cAAc;AAAA,EACzB,UAAU;AAAA,EACV,KAAK;AAAA,IACH,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,UAAU;AAAA,IACV,aAAa;AAAA,IACb,iBAAiB;AAAA,EACnB;AAAA,EACA,MAAM;AAAA,IACJ,QAAQ,EAAE,OAAO,CAAC,CAAC,EAAE,YAAY;AAAA,IACjC,UAAU,iBAAiB;AAAA,IAC3B,QAAQ,CAAC,IAAI;AAAA,IACb,cAAc,aAAa,CAAC;AAAA,EAC9B;AAAA,EACA,SAAS;AAAA,IACP,QAAQ;AAAA,MACN,WAAW;AAAA,MACX,QAAQ;AAAA,MACR,UAAU,OAAO,EAAE,KAAK,IAAI,MAAM;AAChC,cAAM,EAAE,UAAU,IAAI,MAAM,oBAAoB;AAChD,cAAM,SAAS,kBAAkB,OAAO,CAAC,GAAG,KAAK,SAAS;AAC1D,eAAO,8BAA8B,MAAM,MAAM;AAAA,MACnD;AAAA,MACA,UAAU,CAAC,EAAE,OAAO,OAAO;AAAA,QACzB,iBAAiB,QAAQ,mBAAmB;AAAA,MAC9C;AAAA,MACA,QAAQ;AAAA,IACV;AAAA,EACF;AACF,CAAC;AAEM,MAAM,OAAO,KAAK;AAElB,MAAM,UAAU,yBAAyB;AAAA,EAC9C,cAAc;AAAA,EACd,YAAY;AAAA,EACZ,aAAa,EAAE,OAAO,CAAC,CAAC,EAAE,YAAY;AAAA,EACtC,oBAAoB,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;AAAA,EAC5D,QAAQ;AAAA,IACN,QAAQ;AAAA,IACR,gBAAgB;AAAA,IAChB,aACE;AAAA,EAKJ;AACF,CAAC;",
+  "names": []
+}

package/dist/modules/billing/api/usage/route.js

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { makeCrudRoute } from "@open-mercato/shared/lib/crud/factory";
+import { withScopedPayload } from "@open-mercato/shared/lib/api/scoped";
+import { resolveTranslations } from "@open-mercato/shared/lib/i18n/server";
+import { BillingAccountUsage } from "../../data/entities.js";
+import { billingEntityIds } from "../../data/entityIds.js";
+import {
+  billingUsageCreateSchema,
+  billingUsageListQuerySchema
+} from "../../data/validators.js";
+import {
+  createBillingCrudOpenApi,
+  createPagedListResponseSchema
+} from "../openapi.js";
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ["billing.usage.view"] },
+  POST: { requireAuth: true, requireFeatures: ["billing.usage.ingest"] }
+};
+const metadata = routeMetadata;
+const billingUsageListItemSchema = z.object({
+  id: z.string().uuid(),
+  billAccountId: z.string().uuid(),
+  uomCode: z.string(),
+  quantity: z.string(),
+  // numeric(18,4) → string
+  periodStart: z.string(),
+  periodEnd: z.string(),
+  lineDescription: z.string().nullable(),
+  sourceRef: z.string().nullable(),
+  ratedInBillRunId: z.string().uuid().nullable(),
+  isActive: z.boolean(),
+  organizationId: z.string().uuid(),
+  tenantId: z.string().uuid(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+const usageCreateResponseSchema = z.object({
+  id: z.string().uuid().nullable(),
+  deduplicated: z.boolean()
+});
+const rawBodySchema = z.object({}).passthrough();
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: BillingAccountUsage,
+    idField: "id",
+    orgField: "organizationId",
+    tenantField: "tenantId",
+    softDeleteField: "deletedAt"
+  },
+  list: {
+    schema: billingUsageListQuerySchema,
+    entityId: billingEntityIds.usage,
+    fields: [
+      "id",
+      "bill_account_id",
+      "uom_code",
+      "quantity",
+      "period_start",
+      "period_end",
+      "line_description",
+      "source_ref",
+      "rated_in_bill_run_id",
+      "is_active",
+      "organization_id",
+      "tenant_id",
+      "created_at",
+      "updated_at"
+    ],
+    sortFieldMap: {
+      createdAt: "created_at",
+      periodStart: "period_start",
+      periodEnd: "period_end"
+    },
+    buildFilters: async (query) => {
+      const filters = {};
+      if (typeof query.billAccountId === "string" && query.billAccountId) {
+        filters.bill_account_id = { $eq: query.billAccountId };
+      }
+      if (typeof query.uomCode === "string" && query.uomCode) {
+        filters.uom_code = { $eq: query.uomCode };
+      }
+      if (typeof query.rated === "boolean") {
+        filters.rated_in_bill_run_id = query.rated ? { $ne: null } : { $eq: null };
+      }
+      if (query.periodEndFrom instanceof Date) {
+        filters.period_end = Object.assign(
+          filters.period_end ?? {},
+          { $gte: query.periodEndFrom }
+        );
+      }
+      if (query.periodEndTo instanceof Date) {
+        filters.period_end = Object.assign(
+          filters.period_end ?? {},
+          { $lte: query.periodEndTo }
+        );
+      }
+      return filters;
+    }
+  },
+  actions: {
+    create: {
+      commandId: "billing.usage.create",
+      schema: rawBodySchema,
+      mapInput: async ({ raw, ctx }) => {
+        const { translate } = await resolveTranslations();
+        const scoped = withScopedPayload(raw ?? {}, ctx, translate);
+        return billingUsageCreateSchema.parse(scoped);
+      },
+      response: ({ result }) => ({
+        id: result?.id ?? null,
+        deduplicated: Boolean(result?.deduplicated)
+      }),
+      status: 200
+    }
+    // Usage has no update or delete by design — see file header.
+  }
+});
+const { POST } = crud;
+const GET = crud.GET;
+const openApi = createBillingCrudOpenApi({
+  resourceName: "BillingUsageRecord",
+  pluralName: "BillingUsageRecords",
+  querySchema: billingUsageListQuerySchema,
+  listResponseSchema: createPagedListResponseSchema(billingUsageListItemSchema),
+  create: {
+    schema: billingUsageCreateSchema,
+    responseSchema: usageCreateResponseSchema,
+    description: "Ingests a pre-aggregated usage record. Idempotent via `sourceRef`. Usage records are immutable once persisted \u2014 to correct a mis-aggregation, post a `one_time` Billing Item credit (the spec's refund model)."
+  }
+});
+export {
+  GET,
+  POST,
+  metadata,
+  openApi
+};
+//# sourceMappingURL=route.js.map

package/dist/modules/billing/api/usage/route.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/modules/billing/api/usage/route.ts"],
+  "sourcesContent": ["import { z } from 'zod'\nimport { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'\nimport { withScopedPayload } from '@open-mercato/shared/lib/api/scoped'\nimport { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'\nimport { BillingAccountUsage } from '../../data/entities'\nimport { billingEntityIds } from '../../data/entityIds'\nimport {\n  billingUsageCreateSchema,\n  billingUsageListQuerySchema,\n} from '../../data/validators'\nimport {\n  createBillingCrudOpenApi,\n  createPagedListResponseSchema,\n} from '../openapi'\n\n// \u2500\u2500\u2500 Auth / RBAC \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// Usage is append-only \u2014 no update or delete. The narrow scope here\n// lets us mint API keys for external metering systems with ONLY\n// `billing.usage.ingest`, eliminating an entire blast radius.\n\nconst routeMetadata = {\n  GET: { requireAuth: true, requireFeatures: ['billing.usage.view'] },\n  POST: { requireAuth: true, requireFeatures: ['billing.usage.ingest'] },\n}\n\nexport const metadata = routeMetadata\n\nconst billingUsageListItemSchema = z.object({\n  id: z.string().uuid(),\n  billAccountId: z.string().uuid(),\n  uomCode: z.string(),\n  quantity: z.string(), // numeric(18,4) \u2192 string\n  periodStart: z.string(),\n  periodEnd: z.string(),\n  lineDescription: z.string().nullable(),\n  sourceRef: z.string().nullable(),\n  ratedInBillRunId: z.string().uuid().nullable(),\n  isActive: z.boolean(),\n  organizationId: z.string().uuid(),\n  tenantId: z.string().uuid(),\n  createdAt: z.string(),\n  updatedAt: z.string(),\n})\n\nconst usageCreateResponseSchema = z.object({\n  id: z.string().uuid().nullable(),\n  deduplicated: z.boolean(),\n})\n\nconst rawBodySchema = z.object({}).passthrough()\n\nconst crud = makeCrudRoute({\n  metadata: routeMetadata,\n  orm: {\n    entity: BillingAccountUsage,\n    idField: 'id',\n    orgField: 'organizationId',\n    tenantField: 'tenantId',\n    softDeleteField: 'deletedAt',\n  },\n  list: {\n    schema: billingUsageListQuerySchema,\n    entityId: billingEntityIds.usage,\n    fields: [\n      'id',\n      'bill_account_id',\n      'uom_code',\n      'quantity',\n      'period_start',\n      'period_end',\n      'line_description',\n      'source_ref',\n      'rated_in_bill_run_id',\n      'is_active',\n      'organization_id',\n      'tenant_id',\n      'created_at',\n      'updated_at',\n    ],\n    sortFieldMap: {\n      createdAt: 'created_at',\n      periodStart: 'period_start',\n      periodEnd: 'period_end',\n    },\n    buildFilters: async (query) => {\n      const filters: Record<string, unknown> = {}\n      if (typeof query.billAccountId === 'string' && query.billAccountId) {\n        filters.bill_account_id = { $eq: query.billAccountId }\n      }\n      if (typeof query.uomCode === 'string' && query.uomCode) {\n        filters.uom_code = { $eq: query.uomCode }\n      }\n      if (typeof query.rated === 'boolean') {\n        filters.rated_in_bill_run_id = query.rated ? { $ne: null } : { $eq: null }\n      }\n      if (query.periodEndFrom instanceof Date) {\n        filters.period_end = Object.assign(\n          (filters.period_end as Record<string, unknown>) ?? {},\n          { $gte: query.periodEndFrom },\n        )\n      }\n      if (query.periodEndTo instanceof Date) {\n        filters.period_end = Object.assign(\n          (filters.period_end as Record<string, unknown>) ?? {},\n          { $lte: query.periodEndTo },\n        )\n      }\n      return filters\n    },\n  },\n  actions: {\n    create: {\n      commandId: 'billing.usage.create',\n      schema: rawBodySchema,\n      mapInput: async ({ raw, ctx }) => {\n        const { translate } = await resolveTranslations()\n        const scoped = withScopedPayload(raw ?? {}, ctx, translate)\n        return billingUsageCreateSchema.parse(scoped)\n      },\n      response: ({ result }) => ({\n        id: result?.id ?? null,\n        deduplicated: Boolean(result?.deduplicated),\n      }),\n      status: 200,\n    },\n    // Usage has no update or delete by design \u2014 see file header.\n  },\n})\n\nconst { POST } = crud\nexport { POST }\nexport const GET = crud.GET\n\nexport const openApi = createBillingCrudOpenApi({\n  resourceName: 'BillingUsageRecord',\n  pluralName: 'BillingUsageRecords',\n  querySchema: billingUsageListQuerySchema,\n  listResponseSchema: createPagedListResponseSchema(billingUsageListItemSchema),\n  create: {\n    schema: billingUsageCreateSchema,\n    responseSchema: usageCreateResponseSchema,\n    description:\n      'Ingests a pre-aggregated usage record. Idempotent via `sourceRef`. ' +\n      'Usage records are immutable once persisted \u2014 to correct a mis-aggregation, ' +\n      \"post a `one_time` Billing Item credit (the spec's refund model).\",\n  },\n})\n"],
+  "mappings": "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",
+  "names": []
+}