@blazingagents/sdk 0.9.3 → 0.10.0

package/dist/contracts/entities/merchant.d.ts

@@ -0,0 +1,448 @@
+import { z } from "zod";
+/**
+ * Tenant-owned merchant monetization wire entities (ADR-0048). Credentials
+ * never appear here — only the display fragment survives serialization.
+ */
+export declare const merchantProviderSchema: z.ZodEnum<{
+    dodo: "dodo";
+    polar: "polar";
+}>;
+export type MerchantProviderKind = z.infer<typeof merchantProviderSchema>;
+export declare const merchantEnvironmentSchema: z.ZodEnum<{
+    live: "live";
+    sandbox: "sandbox";
+}>;
+export declare const merchantConnectionStatusSchema: z.ZodEnum<{
+    active: "active";
+    disconnected: "disconnected";
+}>;
+export declare const merchantGuardSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    productIds: z.ZodArray<z.ZodString>;
+    meterId: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type MerchantGuard = z.infer<typeof merchantGuardSchema>;
+export declare const merchantConnectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    provider: z.ZodEnum<{
+        dodo: "dodo";
+        polar: "polar";
+    }>;
+    environment: z.ZodEnum<{
+        live: "live";
+        sandbox: "sandbox";
+    }>;
+    status: z.ZodEnum<{
+        active: "active";
+        disconnected: "disconnected";
+    }>;
+    merchantAccountId: z.ZodString;
+    keyFragment: z.ZodString;
+    guard: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        productIds: z.ZodArray<z.ZodString>;
+        meterId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    configVersion: z.ZodNumber;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type MerchantConnection = z.infer<typeof merchantConnectionSchema>;
+export declare const merchantConnectionResponseSchema: z.ZodObject<{
+    connection: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        provider: z.ZodEnum<{
+            dodo: "dodo";
+            polar: "polar";
+        }>;
+        environment: z.ZodEnum<{
+            live: "live";
+            sandbox: "sandbox";
+        }>;
+        status: z.ZodEnum<{
+            active: "active";
+            disconnected: "disconnected";
+        }>;
+        merchantAccountId: z.ZodString;
+        keyFragment: z.ZodString;
+        guard: z.ZodObject<{
+            enabled: z.ZodBoolean;
+            productIds: z.ZodArray<z.ZodString>;
+            meterId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        configVersion: z.ZodNumber;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MerchantConnectionResponse = z.infer<typeof merchantConnectionResponseSchema>;
+export declare const createMerchantConnectionBodySchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        dodo: "dodo";
+        polar: "polar";
+    }>;
+    environment: z.ZodEnum<{
+        live: "live";
+        sandbox: "sandbox";
+    }>;
+    credential: z.ZodString;
+    guard: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        productIds: z.ZodArray<z.ZodString>;
+        meterId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CreateMerchantConnectionBody = z.infer<typeof createMerchantConnectionBodySchema>;
+export declare const updateMerchantConnectionBodySchema: z.ZodObject<{
+    credential: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disconnected: "disconnected";
+    }>>;
+    guard: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        productIds: z.ZodArray<z.ZodString>;
+        meterId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type UpdateMerchantConnectionBody = z.infer<typeof updateMerchantConnectionBodySchema>;
+export declare const merchantCustomerBindingSchema: z.ZodObject<{
+    userId: z.ZodString;
+    customerId: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type MerchantCustomerBinding = z.infer<typeof merchantCustomerBindingSchema>;
+export declare const merchantBindingsListQuerySchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+export declare const merchantBindingsResponseSchema: z.ZodObject<{
+    bindings: z.ZodArray<z.ZodObject<{
+        userId: z.ZodString;
+        customerId: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type MerchantBindingsResponse = z.infer<typeof merchantBindingsResponseSchema>;
+export declare const upsertMerchantBindingBodySchema: z.ZodObject<{
+    customerId: z.ZodString;
+}, z.core.$strict>;
+export type UpsertMerchantBindingBody = z.infer<typeof upsertMerchantBindingBodySchema>;
+export declare const merchantBindingResponseSchema: z.ZodObject<{
+    binding: z.ZodObject<{
+        userId: z.ZodString;
+        customerId: z.ZodString;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type MerchantBindingResponse = z.infer<typeof merchantBindingResponseSchema>;
+export declare const merchantUsageEventStatusSchema: z.ZodEnum<{
+    accepted: "accepted";
+    discarded: "discarded";
+    expired: "expired";
+    failed: "failed";
+    incomplete: "incomplete";
+    pending: "pending";
+    uncertain: "uncertain";
+    unmapped: "unmapped";
+}>;
+export type MerchantUsageEventStatus = z.infer<typeof merchantUsageEventStatusSchema>;
+export declare const merchantWorkflowIssueSchema: z.ZodEnum<{
+    cancelled: "cancelled";
+    error: "error";
+    recovery_exhausted: "recovery_exhausted";
+}>;
+export declare const merchantUsageEventNextActionSchema: z.ZodEnum<{
+    bind_and_release: "bind_and_release";
+    discard: "discard";
+    investigate: "investigate";
+    none: "none";
+    retry: "retry";
+    wait: "wait";
+}>;
+export declare const merchantUsageEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    turnId: z.ZodString;
+    connectionId: z.ZodString;
+    provider: z.ZodEnum<{
+        dodo: "dodo";
+        polar: "polar";
+    }>;
+    userId: z.ZodString;
+    customerId: z.ZodNullable<z.ZodString>;
+    agentId: z.ZodString;
+    sessionId: z.ZodNullable<z.ZodString>;
+    model: z.ZodString;
+    modelProvider: z.ZodEnum<{
+        anthropic: "anthropic";
+        custom: "custom";
+        google: "google";
+        openai: "openai";
+        openrouter: "openrouter";
+        vercel_ai_gateway: "vercel_ai_gateway";
+    }>;
+    inputTokens: z.ZodNumber;
+    outputTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+    turnStatus: z.ZodEnum<{
+        cancelled: "cancelled";
+        failed: "failed";
+        succeeded: "succeeded";
+    }>;
+    startedAt: z.ZodISODateTime;
+    occurredAt: z.ZodISODateTime;
+    status: z.ZodEnum<{
+        accepted: "accepted";
+        discarded: "discarded";
+        expired: "expired";
+        failed: "failed";
+        incomplete: "incomplete";
+        pending: "pending";
+        uncertain: "uncertain";
+        unmapped: "unmapped";
+    }>;
+    payload: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    attemptCount: z.ZodNumber;
+    attemptGeneration: z.ZodNumber;
+    lastAttemptAt: z.ZodNullable<z.ZodISODateTime>;
+    lastErrorCode: z.ZodNullable<z.ZodString>;
+    acceptedAt: z.ZodNullable<z.ZodISODateTime>;
+    workflowIssue: z.ZodNullable<z.ZodEnum<{
+        cancelled: "cancelled";
+        error: "error";
+        recovery_exhausted: "recovery_exhausted";
+    }>>;
+    nextAction: z.ZodEnum<{
+        bind_and_release: "bind_and_release";
+        discard: "discard";
+        investigate: "investigate";
+        none: "none";
+        retry: "retry";
+        wait: "wait";
+    }>;
+}, z.core.$strip>;
+export type MerchantUsageEvent = z.infer<typeof merchantUsageEventSchema>;
+export declare const merchantUsageEventResponseSchema: z.ZodObject<{
+    event: z.ZodObject<{
+        id: z.ZodString;
+        turnId: z.ZodString;
+        connectionId: z.ZodString;
+        provider: z.ZodEnum<{
+            dodo: "dodo";
+            polar: "polar";
+        }>;
+        userId: z.ZodString;
+        customerId: z.ZodNullable<z.ZodString>;
+        agentId: z.ZodString;
+        sessionId: z.ZodNullable<z.ZodString>;
+        model: z.ZodString;
+        modelProvider: z.ZodEnum<{
+            anthropic: "anthropic";
+            custom: "custom";
+            google: "google";
+            openai: "openai";
+            openrouter: "openrouter";
+            vercel_ai_gateway: "vercel_ai_gateway";
+        }>;
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        totalTokens: z.ZodNumber;
+        turnStatus: z.ZodEnum<{
+            cancelled: "cancelled";
+            failed: "failed";
+            succeeded: "succeeded";
+        }>;
+        startedAt: z.ZodISODateTime;
+        occurredAt: z.ZodISODateTime;
+        status: z.ZodEnum<{
+            accepted: "accepted";
+            discarded: "discarded";
+            expired: "expired";
+            failed: "failed";
+            incomplete: "incomplete";
+            pending: "pending";
+            uncertain: "uncertain";
+            unmapped: "unmapped";
+        }>;
+        payload: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        attemptCount: z.ZodNumber;
+        attemptGeneration: z.ZodNumber;
+        lastAttemptAt: z.ZodNullable<z.ZodISODateTime>;
+        lastErrorCode: z.ZodNullable<z.ZodString>;
+        acceptedAt: z.ZodNullable<z.ZodISODateTime>;
+        workflowIssue: z.ZodNullable<z.ZodEnum<{
+            cancelled: "cancelled";
+            error: "error";
+            recovery_exhausted: "recovery_exhausted";
+        }>>;
+        nextAction: z.ZodEnum<{
+            bind_and_release: "bind_and_release";
+            discard: "discard";
+            investigate: "investigate";
+            none: "none";
+            retry: "retry";
+            wait: "wait";
+        }>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type MerchantUsageEventResponse = z.infer<typeof merchantUsageEventResponseSchema>;
+export declare const merchantUsageEventsListQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        accepted: "accepted";
+        discarded: "discarded";
+        expired: "expired";
+        failed: "failed";
+        incomplete: "incomplete";
+        pending: "pending";
+        uncertain: "uncertain";
+        unmapped: "unmapped";
+    }>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+export declare const merchantUsageEventsResponseSchema: z.ZodObject<{
+    events: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        turnId: z.ZodString;
+        connectionId: z.ZodString;
+        provider: z.ZodEnum<{
+            dodo: "dodo";
+            polar: "polar";
+        }>;
+        userId: z.ZodString;
+        customerId: z.ZodNullable<z.ZodString>;
+        agentId: z.ZodString;
+        sessionId: z.ZodNullable<z.ZodString>;
+        model: z.ZodString;
+        modelProvider: z.ZodEnum<{
+            anthropic: "anthropic";
+            custom: "custom";
+            google: "google";
+            openai: "openai";
+            openrouter: "openrouter";
+            vercel_ai_gateway: "vercel_ai_gateway";
+        }>;
+        inputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        totalTokens: z.ZodNumber;
+        turnStatus: z.ZodEnum<{
+            cancelled: "cancelled";
+            failed: "failed";
+            succeeded: "succeeded";
+        }>;
+        startedAt: z.ZodISODateTime;
+        occurredAt: z.ZodISODateTime;
+        status: z.ZodEnum<{
+            accepted: "accepted";
+            discarded: "discarded";
+            expired: "expired";
+            failed: "failed";
+            incomplete: "incomplete";
+            pending: "pending";
+            uncertain: "uncertain";
+            unmapped: "unmapped";
+        }>;
+        payload: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        attemptCount: z.ZodNumber;
+        attemptGeneration: z.ZodNumber;
+        lastAttemptAt: z.ZodNullable<z.ZodISODateTime>;
+        lastErrorCode: z.ZodNullable<z.ZodString>;
+        acceptedAt: z.ZodNullable<z.ZodISODateTime>;
+        workflowIssue: z.ZodNullable<z.ZodEnum<{
+            cancelled: "cancelled";
+            error: "error";
+            recovery_exhausted: "recovery_exhausted";
+        }>>;
+        nextAction: z.ZodEnum<{
+            bind_and_release: "bind_and_release";
+            discard: "discard";
+            investigate: "investigate";
+            none: "none";
+            retry: "retry";
+            wait: "wait";
+        }>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type MerchantUsageEventsResponse = z.infer<typeof merchantUsageEventsResponseSchema>;
+/**
+ * Delivery-health aggregate behind `GET /v1/merchant-usage-events/summary` —
+ * all-time status counts plus a UTC daily window so a dashboard can show
+ * whether deliveries are flowing without scanning the ledger.
+ */
+export declare const merchantUsageSummaryCountsSchema: z.ZodObject<{
+    pending: z.ZodNumber;
+    accepted: z.ZodNumber;
+    uncertain: z.ZodNumber;
+    failed: z.ZodNumber;
+    unmapped: z.ZodNumber;
+    incomplete: z.ZodNumber;
+    expired: z.ZodNumber;
+    discarded: z.ZodNumber;
+}, z.core.$strict>;
+export declare const merchantUsageSummaryDaySchema: z.ZodObject<{
+    day: z.ZodISODate;
+    acceptedEvents: z.ZodNumber;
+    acceptedTokens: z.ZodNumber;
+    pendingEvents: z.ZodNumber;
+}, z.core.$strict>;
+export declare const merchantUsageSummarySchema: z.ZodObject<{
+    counts: z.ZodObject<{
+        pending: z.ZodNumber;
+        accepted: z.ZodNumber;
+        uncertain: z.ZodNumber;
+        failed: z.ZodNumber;
+        unmapped: z.ZodNumber;
+        incomplete: z.ZodNumber;
+        expired: z.ZodNumber;
+        discarded: z.ZodNumber;
+    }, z.core.$strict>;
+    lastAcceptedAt: z.ZodNullable<z.ZodISODateTime>;
+    oldestPendingOccurredAt: z.ZodNullable<z.ZodISODateTime>;
+    daily: z.ZodArray<z.ZodObject<{
+        day: z.ZodISODate;
+        acceptedEvents: z.ZodNumber;
+        acceptedTokens: z.ZodNumber;
+        pendingEvents: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type MerchantUsageSummary = z.infer<typeof merchantUsageSummarySchema>;
+export declare const merchantUsageSummaryQuerySchema: z.ZodObject<{
+    days: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+export declare const merchantUsageSummaryResponseSchema: z.ZodObject<{
+    summary: z.ZodObject<{
+        counts: z.ZodObject<{
+            pending: z.ZodNumber;
+            accepted: z.ZodNumber;
+            uncertain: z.ZodNumber;
+            failed: z.ZodNumber;
+            unmapped: z.ZodNumber;
+            incomplete: z.ZodNumber;
+            expired: z.ZodNumber;
+            discarded: z.ZodNumber;
+        }, z.core.$strict>;
+        lastAcceptedAt: z.ZodNullable<z.ZodISODateTime>;
+        oldestPendingOccurredAt: z.ZodNullable<z.ZodISODateTime>;
+        daily: z.ZodArray<z.ZodObject<{
+            day: z.ZodISODate;
+            acceptedEvents: z.ZodNumber;
+            acceptedTokens: z.ZodNumber;
+            pendingEvents: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strip>;
+export type MerchantUsageSummaryResponse = z.infer<typeof merchantUsageSummaryResponseSchema>;
+/**
+ * The operator-facing action derived from event state — computed at the
+ * service seam, never persisted.
+ */
+export declare function merchantUsageEventNextAction(event: {
+    status: MerchantUsageEventStatus;
+    workflowIssue: z.infer<typeof merchantWorkflowIssueSchema> | null;
+}): z.infer<typeof merchantUsageEventNextActionSchema>;

package/dist/contracts/entities/merchant.js

@@ -0,0 +1,237 @@
+import { z } from "zod";
+import { cursorSchema } from "../api.js";
+import { agentIdSchema, merchantConnectionIdSchema, merchantUsageEventIdSchema, providerKeyFragmentSchema, sessionIdSchema, turnIdSchema, } from "../ids.js";
+import { DEFAULT_MERCHANT_LIST_LIMIT, DEFAULT_MERCHANT_USAGE_SUMMARY_DAYS, MAX_MERCHANT_LIST_LIMIT, MAX_MERCHANT_PRODUCT_IDS, MAX_MERCHANT_USAGE_SUMMARY_DAYS, } from "../limitations.js";
+import { hasUniqueValues } from "../utils.js";
+import { userIdSchema } from "./attribution.js";
+import { providerTypeSchema } from "./providers.js";
+/**
+ * Tenant-owned merchant monetization wire entities (ADR-0048). Credentials
+ * never appear here — only the display fragment survives serialization.
+ */
+export const merchantProviderSchema = z.enum(["polar", "dodo"]);
+export const merchantEnvironmentSchema = z.enum(["sandbox", "live"]);
+export const merchantConnectionStatusSchema = z.enum([
+    "active",
+    "disconnected",
+]);
+export const merchantGuardSchema = z
+    .object({
+    enabled: z.boolean(),
+    productIds: z
+        .array(z.string().min(1))
+        .max(MAX_MERCHANT_PRODUCT_IDS)
+        .refine(hasUniqueValues, {
+        message: "Guard product ids must be unique.",
+    }),
+    meterId: z.string().min(1).nullable(),
+})
+    .strict()
+    .refine((guard) => !guard.enabled || guard.productIds.length > 0 || guard.meterId !== null, {
+    message: "An enabled guard requires at least one product id or a meter id.",
+});
+export const merchantConnectionSchema = z
+    .object({
+    id: merchantConnectionIdSchema,
+    provider: merchantProviderSchema,
+    environment: merchantEnvironmentSchema,
+    status: merchantConnectionStatusSchema,
+    merchantAccountId: z.string().min(1),
+    keyFragment: providerKeyFragmentSchema,
+    guard: merchantGuardSchema,
+    configVersion: z.number().int().min(1),
+    createdAt: z.iso.datetime({ offset: true }),
+    updatedAt: z.iso.datetime({ offset: true }),
+})
+    .strip();
+export const merchantConnectionResponseSchema = z
+    .object({ connection: merchantConnectionSchema.nullable() })
+    .strip();
+export const createMerchantConnectionBodySchema = z
+    .object({
+    provider: merchantProviderSchema,
+    environment: merchantEnvironmentSchema,
+    credential: z.string().min(1),
+    guard: merchantGuardSchema.optional(),
+})
+    .strict();
+export const updateMerchantConnectionBodySchema = z
+    .object({
+    credential: z.string().min(1).optional(),
+    status: merchantConnectionStatusSchema.optional(),
+    guard: merchantGuardSchema.optional(),
+})
+    .strict();
+export const merchantCustomerBindingSchema = z
+    .object({
+    userId: userIdSchema.min(1),
+    customerId: z.string().min(1),
+    createdAt: z.iso.datetime({ offset: true }),
+    updatedAt: z.iso.datetime({ offset: true }),
+})
+    .strip();
+export const merchantBindingsListQuerySchema = z
+    .object({
+    userId: userIdSchema.optional(),
+    cursor: cursorSchema.optional(),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_MERCHANT_LIST_LIMIT)
+        .default(DEFAULT_MERCHANT_LIST_LIMIT),
+})
+    .strict();
+export const merchantBindingsResponseSchema = z
+    .object({
+    bindings: z.array(merchantCustomerBindingSchema),
+    nextCursor: z.string().nullable(),
+})
+    .strip();
+export const upsertMerchantBindingBodySchema = z
+    .object({ customerId: z.string().min(1) })
+    .strict();
+export const merchantBindingResponseSchema = z
+    .object({ binding: merchantCustomerBindingSchema })
+    .strip();
+export const merchantUsageEventStatusSchema = z.enum([
+    "pending",
+    "accepted",
+    "failed",
+    "uncertain",
+    "unmapped",
+    "incomplete",
+    "discarded",
+    "expired",
+]);
+export const merchantWorkflowIssueSchema = z.enum([
+    "error",
+    "cancelled",
+    "recovery_exhausted",
+]);
+export const merchantUsageEventNextActionSchema = z.enum([
+    "none",
+    "wait",
+    "retry",
+    "bind_and_release",
+    "investigate",
+    "discard",
+]);
+export const merchantUsageEventSchema = z
+    .object({
+    id: merchantUsageEventIdSchema,
+    turnId: turnIdSchema,
+    connectionId: merchantConnectionIdSchema,
+    provider: merchantProviderSchema,
+    userId: userIdSchema,
+    customerId: z.string().min(1).nullable(),
+    agentId: agentIdSchema,
+    sessionId: sessionIdSchema.nullable(),
+    model: z.string().min(1),
+    modelProvider: providerTypeSchema,
+    inputTokens: z.number().int().min(0),
+    outputTokens: z.number().int().min(0),
+    totalTokens: z.number().int().min(0),
+    turnStatus: z.enum(["succeeded", "cancelled", "failed"]),
+    startedAt: z.iso.datetime({ offset: true }),
+    occurredAt: z.iso.datetime({ offset: true }),
+    status: merchantUsageEventStatusSchema,
+    payload: z.record(z.string(), z.unknown()).nullable(),
+    attemptCount: z.number().int().min(0),
+    attemptGeneration: z.number().int().min(0),
+    lastAttemptAt: z.iso.datetime({ offset: true }).nullable(),
+    lastErrorCode: z.string().nullable(),
+    acceptedAt: z.iso.datetime({ offset: true }).nullable(),
+    workflowIssue: merchantWorkflowIssueSchema.nullable(),
+    nextAction: merchantUsageEventNextActionSchema,
+})
+    .strip();
+export const merchantUsageEventResponseSchema = z
+    .object({ event: merchantUsageEventSchema })
+    .strip();
+export const merchantUsageEventsListQuerySchema = z
+    .object({
+    status: merchantUsageEventStatusSchema.optional(),
+    cursor: cursorSchema.optional(),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_MERCHANT_LIST_LIMIT)
+        .default(DEFAULT_MERCHANT_LIST_LIMIT),
+})
+    .strict();
+export const merchantUsageEventsResponseSchema = z
+    .object({
+    events: z.array(merchantUsageEventSchema),
+    nextCursor: z.string().nullable(),
+})
+    .strip();
+/**
+ * Delivery-health aggregate behind `GET /v1/merchant-usage-events/summary` —
+ * all-time status counts plus a UTC daily window so a dashboard can show
+ * whether deliveries are flowing without scanning the ledger.
+ */
+export const merchantUsageSummaryCountsSchema = z
+    .object({
+    pending: z.number().int().nonnegative(),
+    accepted: z.number().int().nonnegative(),
+    uncertain: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    unmapped: z.number().int().nonnegative(),
+    incomplete: z.number().int().nonnegative(),
+    expired: z.number().int().nonnegative(),
+    discarded: z.number().int().nonnegative(),
+})
+    .strict();
+export const merchantUsageSummaryDaySchema = z
+    .object({
+    day: z.iso.date(),
+    acceptedEvents: z.number().int().nonnegative(),
+    acceptedTokens: z.number().int().nonnegative(),
+    pendingEvents: z.number().int().nonnegative(),
+})
+    .strict();
+export const merchantUsageSummarySchema = z
+    .object({
+    counts: merchantUsageSummaryCountsSchema,
+    lastAcceptedAt: z.iso.datetime({ offset: true }).nullable(),
+    oldestPendingOccurredAt: z.iso.datetime({ offset: true }).nullable(),
+    daily: z.array(merchantUsageSummaryDaySchema),
+})
+    .strict();
+export const merchantUsageSummaryQuerySchema = z
+    .object({
+    days: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_MERCHANT_USAGE_SUMMARY_DAYS)
+        .default(DEFAULT_MERCHANT_USAGE_SUMMARY_DAYS),
+})
+    .strict();
+export const merchantUsageSummaryResponseSchema = z
+    .object({ summary: merchantUsageSummarySchema })
+    .strip();
+/**
+ * The operator-facing action derived from event state — computed at the
+ * service seam, never persisted.
+ */
+export function merchantUsageEventNextAction(event) {
+    switch (event.status) {
+        case "accepted":
+        case "discarded":
+            return "none";
+        case "pending":
+            return event.workflowIssue === null ? "wait" : "retry";
+        case "failed":
+        case "uncertain":
+            return "retry";
+        case "unmapped":
+            return "bind_and_release";
+        case "incomplete":
+            return "investigate";
+        case "expired":
+            return "discard";
+    }
+}