@springbrand/contracts 0.0.0-stage → 0.1.0-alpha.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @springbrand/contracts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+API、Web、Agent 和 Auth 共用的业务接口合约：每个业务领域的 Zod schema 和推导出的 TypeScript 类型。
+
+## 只用子路径导入
+
+本包没有根入口。每个领域单独导出，例如：
+
+```ts
+import { accountSnapshotSchema, type AccountSnapshot } from '@springbrand/contracts/account'
+import { actionExecutionReplySchema } from '@springbrand/contracts/action'
+```
+
+Zod schema 在模块加载时就会被创建。单一根入口会让每个调用方都创建全部业务 schema，Agent Worker 冷启动会因此变慢，
+所以新增领域时要新建模块，并在 `package.json` 的 `exports` 里加对应子路径。
+
+## 边界
+
+- HTTP 响应信封、客户端、服务鉴权属于上游 `@springbrand/http`。平台错误码目录（`./errors`）和它的 Hono 响应（`./http`）放在这里，因为错误码是平台业务定义。
+- Agent 运行时专用的合约属于 `@springbrand/agent-contracts`；Resource 与能力合约属于 `@springbrand/resource`。
+- `mcp-api-key` 是对外冻结的 MCP Key 合约。mcp-gateway vendor 的外部 tarball 仍叫 `@springbrand/http`（入口 `./mcp-api-key`、`./service-auth`、`./errors`，v2 形状），由
+  `scripts/pack-mcp-contracts.mjs` 生成：`./mcp-api-key` 来自本包，另外两个入口来自 `src/mcp-gateway/` 的兼容层（数据和逻辑取自 `./errors` 与公共 SDK）。改动兼容层或合约后，用新的 `--version` 重新打包，并在 mcp-gateway 里跑一遍 typecheck 和测试。
+
+- `agent-config-deletion` 持有 Agent 删除检查和阻碍事实，供错误目录与 Agent 合约共同使用，避免两者形成循环依赖。

package/dist/contracts/src/account.d.ts

@@ -0,0 +1,300 @@
+import { z } from "zod";
+export declare const subscriptionStatusSchema: z.ZodEnum<{
+    active: "active";
+    canceling: "canceling";
+    past_due: "past_due";
+}>;
+export declare const accountActionSchema: z.ZodEnum<{
+    subscribe: "subscribe";
+    change_plan: "change_plan";
+    cancel_subscription: "cancel_subscription";
+    resume_subscription: "resume_subscription";
+    update_payment_method: "update_payment_method";
+}>;
+export declare const accountSnapshotSchema: z.ZodObject<{
+    asOf: z.ZodString;
+    reconciliationCompleted: z.ZodBoolean;
+    profile: z.ZodObject<{
+        userId: z.ZodString;
+        email: z.ZodEmail;
+        displayName: z.ZodString;
+        avatarUrl: z.ZodNullable<z.ZodString>;
+        timezone: z.ZodString;
+    }, z.core.$strip>;
+    plan: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    subscription: z.ZodNullable<z.ZodObject<{
+        status: z.ZodEnum<{
+            active: "active";
+            canceling: "canceling";
+            past_due: "past_due";
+        }>;
+        billingInterval: z.ZodEnum<{
+            month: "month";
+            year: "year";
+        }>;
+        autoRenews: z.ZodBoolean;
+        planChangeBlockedReason: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            subscription_refunded: "subscription_refunded";
+        }>>>;
+    }, z.core.$strip>>;
+    pendingPlanCheckout: z.ZodNullable<z.ZodObject<{
+        orderId: z.ZodString;
+        planId: z.ZodString;
+        billingInterval: z.ZodEnum<{
+            month: "month";
+            year: "year";
+        }>;
+        status: z.ZodLiteral<"confirmation_pending">;
+    }, z.core.$strip>>;
+    pendingTopupCheckout: z.ZodNullable<z.ZodObject<{
+        orderId: z.ZodString;
+        topupId: z.ZodString;
+        creditQuantity: z.ZodNumber;
+        status: z.ZodLiteral<"confirmation_pending">;
+    }, z.core.$strip>>;
+    creditAccount: z.ZodObject<{
+        availableUnits: z.ZodNumber;
+        topupRemainingUnits: z.ZodNumber;
+        otherRemainingUnits: z.ZodNumber;
+    }, z.core.$strip>;
+    currentCreditPeriod: z.ZodNullable<z.ZodObject<{
+        startsAt: z.ZodString;
+        endsAt: z.ZodString;
+        allowanceUnits: z.ZodNumber;
+        remainingUnits: z.ZodNumber;
+    }, z.core.$strip>>;
+    renewAt: z.ZodNullable<z.ZodString>;
+    planEndsAt: z.ZodNullable<z.ZodString>;
+    nextGrantAt: z.ZodNullable<z.ZodString>;
+    nextExpiryAt: z.ZodNullable<z.ZodString>;
+    allowedActions: z.ZodArray<z.ZodEnum<{
+        subscribe: "subscribe";
+        change_plan: "change_plan";
+        cancel_subscription: "cancel_subscription";
+        resume_subscription: "resume_subscription";
+        update_payment_method: "update_payment_method";
+    }>>;
+}, z.core.$strip>;
+export declare const planChangeRequestSchema: z.ZodObject<{
+    planId: z.ZodString;
+    billingInterval: z.ZodEnum<{
+        month: "month";
+        year: "year";
+    }>;
+    returnPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const planCheckoutRequestSchema: z.ZodObject<{
+    planId: z.ZodString;
+    billingInterval: z.ZodEnum<{
+        month: "month";
+        year: "year";
+    }>;
+    idempotencyKey: z.ZodUUID;
+    returnPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const topupCheckoutRequestSchema: z.ZodObject<{
+    topupId: z.ZodString;
+    idempotencyKey: z.ZodUUID;
+    returnPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const planChangeSchema: z.ZodObject<{
+    confirmationUrl: z.ZodURL;
+}, z.core.$strip>;
+export declare const planCatalogSchema: z.ZodObject<{
+    freePlan: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        allowanceUnits: z.ZodNumber;
+    }, z.core.$strip>;
+    plans: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        allowanceUnits: z.ZodOptional<z.ZodNumber>;
+        topupBonusPercent: z.ZodOptional<z.ZodNumber>;
+        billingOptions: z.ZodArray<z.ZodObject<{
+            billingInterval: z.ZodEnum<{
+                month: "month";
+                year: "year";
+            }>;
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const topupCatalogSchema: z.ZodObject<{
+    topups: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        baseCreditQuantity: z.ZodNumber;
+        bonusCreditQuantity: z.ZodNumber;
+        effectiveCreditQuantity: z.ZodNumber;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const topupCatalogQuerySchema: z.ZodObject<{
+    planId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const accountActivitySchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        category: z.ZodEnum<{
+            credit: "credit";
+            spend: "spend";
+            removal: "removal";
+        }>;
+        title: z.ZodString;
+        context: z.ZodString;
+        amount: z.ZodNumber;
+        availableAfter: z.ZodNumber;
+        createdAt: z.ZodString;
+        chatId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    nextBefore: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const accountRateCardSchema: z.ZodObject<{
+    rateVersion: z.ZodNumber;
+    effectiveAtMs: z.ZodNumber;
+    creditValue: z.ZodNullable<z.ZodObject<{
+        basis: z.ZodLiteral<"plus_topup">;
+        packageId: z.ZodString;
+        currency: z.ZodString;
+        amountUsd: z.ZodNumber;
+        effectiveCredits: z.ZodNumber;
+        creditsPerUsd: z.ZodNumber;
+        usdPerCredit: z.ZodNumber;
+    }, z.core.$strip>>;
+    meters: z.ZodArray<z.ZodObject<{
+        meterId: z.ZodString;
+        provider: z.ZodString;
+        model: z.ZodString;
+        prices: z.ZodObject<{
+            inputTokens: z.ZodOptional<z.ZodObject<{
+                credits: z.ZodNumber;
+                per: z.ZodNumber;
+            }, z.core.$strip>>;
+            outputTokens: z.ZodOptional<z.ZodObject<{
+                credits: z.ZodNumber;
+                per: z.ZodNumber;
+            }, z.core.$strip>>;
+            cacheReadTokens: z.ZodOptional<z.ZodObject<{
+                credits: z.ZodNumber;
+                per: z.ZodNumber;
+            }, z.core.$strip>>;
+            cacheWriteTokens: z.ZodOptional<z.ZodObject<{
+                credits: z.ZodNumber;
+                per: z.ZodNumber;
+            }, z.core.$strip>>;
+            reasoningTokens: z.ZodOptional<z.ZodObject<{
+                credits: z.ZodNumber;
+                per: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        providerCost: z.ZodNullable<z.ZodObject<{
+            provider: z.ZodLiteral<"openrouter">;
+            inputUsdPer1M: z.ZodNumber;
+            outputUsdPer1M: z.ZodNumber;
+            fetchedAt: z.ZodString;
+        }, z.core.$strip>>;
+        economics: z.ZodObject<{
+            input: z.ZodNullable<z.ZodObject<{
+                revenueUsdPer1M: z.ZodNumber;
+                providerCostUsdPer1M: z.ZodNumber;
+                grossProfitUsdPer1M: z.ZodNumber;
+                grossMarginPct: z.ZodNumber;
+            }, z.core.$strip>>;
+            output: z.ZodNullable<z.ZodObject<{
+                revenueUsdPer1M: z.ZodNumber;
+                providerCostUsdPer1M: z.ZodNumber;
+                grossProfitUsdPer1M: z.ZodNumber;
+                grossMarginPct: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const accountUsageDetailsSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        eventId: z.ZodString;
+        runId: z.ZodString;
+        chatId: z.ZodNullable<z.ZodString>;
+        chatTitle: z.ZodNullable<z.ZodString>;
+        subagentRunId: z.ZodNullable<z.ZodString>;
+        parentRunId: z.ZodNullable<z.ZodString>;
+        kind: z.ZodEnum<{
+            assistant_model: "assistant_model";
+            compaction: "compaction";
+            subagent: "subagent";
+            chat_title: "chat_title";
+        }>;
+        outcome: z.ZodEnum<{
+            billable: "billable";
+            user_cancelled: "user_cancelled";
+            system_failure: "system_failure";
+            provider_failure: "provider_failure";
+            missing_trusted_usage: "missing_trusted_usage";
+        }>;
+        status: z.ZodEnum<{
+            settled: "settled";
+            platform_owned: "platform_owned";
+            anomaly: "anomaly";
+        }>;
+        rateVersion: z.ZodNumber;
+        meterId: z.ZodString;
+        provider: z.ZodString;
+        model: z.ZodString;
+        metrics: z.ZodObject<{
+            inputTokens: z.ZodNullable<z.ZodNumber>;
+            outputTokens: z.ZodNullable<z.ZodNumber>;
+            cacheReadTokens: z.ZodNullable<z.ZodNumber>;
+            cacheWriteTokens: z.ZodNullable<z.ZodNumber>;
+            reasoningTokens: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>;
+        ratedUnits: z.ZodNullable<z.ZodNumber>;
+        debitedUnits: z.ZodNumber;
+        shortfallUnits: z.ZodNumber;
+        platformOwnedUnits: z.ZodNullable<z.ZodNumber>;
+        platformOwnedReason: z.ZodNullable<z.ZodEnum<{
+            chat_title: "chat_title";
+            system_failure: "system_failure";
+            provider_failure: "provider_failure";
+            missing_trusted_usage: "missing_trusted_usage";
+            insufficient_balance: "insufficient_balance";
+        }>>;
+        availableAfter: z.ZodNullable<z.ZodNumber>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+    nextBefore: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AccountActivity = z.infer<typeof accountActivitySchema>;
+export type AccountAction = z.infer<typeof accountActionSchema>;
+export type AccountSnapshot = z.infer<typeof accountSnapshotSchema>;
+export type AccountRateCard = z.infer<typeof accountRateCardSchema>;
+export type AccountUsageDetails = z.infer<typeof accountUsageDetailsSchema>;
+export type PlanCatalog = z.infer<typeof planCatalogSchema>;
+export type PlanChange = z.infer<typeof planChangeSchema>;
+export type PlanChangeRequest = z.infer<typeof planChangeRequestSchema>;
+export type PlanCheckoutRequest = z.infer<typeof planCheckoutRequestSchema>;
+export type TopupCheckoutRequest = z.infer<typeof topupCheckoutRequestSchema>;
+export type SubscriptionStatus = z.infer<typeof subscriptionStatusSchema>;
+export type TopupCatalog = z.infer<typeof topupCatalogSchema>;
+export type TopupCatalogQuery = z.infer<typeof topupCatalogQuerySchema>;
+export declare const mockCreditCheckoutRequestSchema: z.ZodObject<{
+    orderId: z.ZodUUID;
+    priceId: z.ZodOptional<z.ZodString>;
+    outcome: z.ZodEnum<{
+        paid: "paid";
+        cancelled: "cancelled";
+    }>;
+}, z.core.$strict>;
+export declare const mockCreditCheckoutResultSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        paid: "paid";
+        cancelled: "cancelled";
+    }>;
+}, z.core.$strip>;
+export type MockCreditCheckoutRequest = z.infer<typeof mockCreditCheckoutRequestSchema>;
+export type MockCreditCheckoutResult = z.infer<typeof mockCreditCheckoutResultSchema>;

package/dist/contracts/src/account.js

@@ -0,0 +1,211 @@
+import { z } from "zod";
+export const subscriptionStatusSchema = z.enum(["active", "canceling", "past_due"]);
+export const accountActionSchema = z.enum([
+    "subscribe",
+    "change_plan",
+    "cancel_subscription",
+    "resume_subscription",
+    "update_payment_method",
+]);
+export const accountSnapshotSchema = z.object({
+    asOf: z.string(),
+    reconciliationCompleted: z.boolean(),
+    profile: z.object({
+        userId: z.string(),
+        email: z.email(),
+        displayName: z.string(),
+        avatarUrl: z.string().nullable(),
+        timezone: z.string(),
+    }),
+    plan: z.object({ id: z.string(), name: z.string() }),
+    subscription: z.object({
+        status: subscriptionStatusSchema,
+        billingInterval: z.enum(["month", "year"]),
+        autoRenews: z.boolean(),
+        planChangeBlockedReason: z.enum(["subscription_refunded"]).nullable().optional(),
+    }).nullable(),
+    pendingPlanCheckout: z.object({
+        orderId: z.string(),
+        planId: z.string(),
+        billingInterval: z.enum(["month", "year"]),
+        status: z.literal("confirmation_pending"),
+    }).nullable(),
+    pendingTopupCheckout: z.object({
+        orderId: z.string(),
+        topupId: z.string(),
+        creditQuantity: z.number().int().positive(),
+        status: z.literal("confirmation_pending"),
+    }).nullable(),
+    creditAccount: z.object({
+        availableUnits: z.number().int(),
+        topupRemainingUnits: z.number().int().nonnegative(),
+        otherRemainingUnits: z.number().int().nonnegative(),
+    }),
+    currentCreditPeriod: z.object({
+        startsAt: z.string(),
+        endsAt: z.string(),
+        allowanceUnits: z.number().int().positive(),
+        remainingUnits: z.number().int().nonnegative(),
+    }).nullable(),
+    renewAt: z.string().nullable(),
+    planEndsAt: z.string().nullable(),
+    nextGrantAt: z.string().nullable(),
+    nextExpiryAt: z.string().nullable(),
+    allowedActions: z.array(accountActionSchema),
+});
+const checkoutReturnPathSchema = z.string().trim().max(2048).optional();
+export const planChangeRequestSchema = z.object({
+    planId: z.string().trim().min(1).max(100),
+    billingInterval: z.enum(["month", "year"]),
+    returnPath: checkoutReturnPathSchema,
+}).strict();
+export const planCheckoutRequestSchema = z.object({
+    planId: z.string().trim().min(1).max(100),
+    billingInterval: z.enum(["month", "year"]),
+    idempotencyKey: z.uuid(),
+    returnPath: checkoutReturnPathSchema,
+}).strict();
+export const topupCheckoutRequestSchema = z.object({
+    topupId: z.string().trim().min(1).max(100),
+    idempotencyKey: z.uuid(),
+    returnPath: checkoutReturnPathSchema,
+}).strict();
+export const planChangeSchema = z.object({
+    confirmationUrl: z.url(),
+});
+export const planCatalogSchema = z.object({
+    freePlan: z.object({
+        id: z.string(),
+        name: z.string(),
+        allowanceUnits: z.number().int().nonnegative(),
+    }),
+    plans: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        allowanceUnits: z.number().int().positive().optional(),
+        topupBonusPercent: z.number().int().nonnegative().optional(),
+        billingOptions: z.array(z.object({
+            billingInterval: z.enum(["month", "year"]),
+            amount: z.number().int().positive(),
+            currency: z.string(),
+        })),
+    })),
+});
+export const topupCatalogSchema = z.object({
+    topups: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        baseCreditQuantity: z.number().int().positive(),
+        bonusCreditQuantity: z.number().int().nonnegative(),
+        effectiveCreditQuantity: z.number().int().positive(),
+        amount: z.number().int().positive(),
+        currency: z.string(),
+    })),
+});
+export const topupCatalogQuerySchema = z.object({
+    planId: z.string().trim().min(1).max(100).optional(),
+});
+export const accountActivitySchema = z.object({
+    items: z.array(z.object({
+        id: z.string(),
+        category: z.enum(["credit", "spend", "removal"]),
+        title: z.string(),
+        context: z.string(),
+        amount: z.number().int(),
+        availableAfter: z.number().int(),
+        createdAt: z.string(),
+        chatId: z.string().uuid().nullable(),
+    })),
+    nextBefore: z.string().nullable(),
+});
+const accountRatePriceSchema = z.object({
+    credits: z.number().int().positive(),
+    per: z.number().int().positive(),
+});
+const accountRateCardUnitEconomicsSchema = z.object({
+    revenueUsdPer1M: z.number().finite().nonnegative(),
+    providerCostUsdPer1M: z.number().finite().nonnegative(),
+    grossProfitUsdPer1M: z.number().finite(),
+    grossMarginPct: z.number().finite(),
+});
+const accountRateCardProviderCostSchema = z.object({
+    provider: z.literal("openrouter"),
+    inputUsdPer1M: z.number().finite().nonnegative(),
+    outputUsdPer1M: z.number().finite().nonnegative(),
+    fetchedAt: z.string().datetime(),
+});
+export const accountRateCardSchema = z.object({
+    rateVersion: z.number().int().positive(),
+    effectiveAtMs: z.number().int().nonnegative(),
+    creditValue: z.object({
+        basis: z.literal("plus_topup"),
+        packageId: z.string(),
+        currency: z.string(),
+        amountUsd: z.number().positive(),
+        effectiveCredits: z.number().int().positive(),
+        creditsPerUsd: z.number().positive(),
+        usdPerCredit: z.number().positive(),
+    }).nullable(),
+    meters: z.array(z.object({
+        meterId: z.string(),
+        provider: z.string(),
+        model: z.string(),
+        prices: z.object({
+            inputTokens: accountRatePriceSchema.optional(),
+            outputTokens: accountRatePriceSchema.optional(),
+            cacheReadTokens: accountRatePriceSchema.optional(),
+            cacheWriteTokens: accountRatePriceSchema.optional(),
+            reasoningTokens: accountRatePriceSchema.optional(),
+        }),
+        providerCost: accountRateCardProviderCostSchema.nullable(),
+        economics: z.object({
+            input: accountRateCardUnitEconomicsSchema.nullable(),
+            output: accountRateCardUnitEconomicsSchema.nullable(),
+        }),
+    })),
+});
+export const accountUsageDetailsSchema = z.object({
+    items: z.array(z.object({
+        id: z.string().uuid(),
+        eventId: z.string(),
+        runId: z.string(),
+        chatId: z.string().uuid().nullable(),
+        chatTitle: z.string().nullable(),
+        subagentRunId: z.string().nullable(),
+        parentRunId: z.string().nullable(),
+        kind: z.enum(["assistant_model", "compaction", "subagent", "chat_title"]),
+        outcome: z.enum(["billable", "user_cancelled", "system_failure", "provider_failure", "missing_trusted_usage"]),
+        status: z.enum(["settled", "platform_owned", "anomaly"]),
+        rateVersion: z.number().int().positive(),
+        meterId: z.string(),
+        provider: z.string(),
+        model: z.string(),
+        metrics: z.object({
+            inputTokens: z.number().int().nonnegative().nullable(),
+            outputTokens: z.number().int().nonnegative().nullable(),
+            cacheReadTokens: z.number().int().nonnegative().nullable(),
+            cacheWriteTokens: z.number().int().nonnegative().nullable(),
+            reasoningTokens: z.number().int().nonnegative().nullable(),
+        }),
+        ratedUnits: z.number().int().nonnegative().nullable(),
+        debitedUnits: z.number().int().nonnegative(),
+        shortfallUnits: z.number().int().nonnegative(),
+        platformOwnedUnits: z.number().int().nonnegative().nullable(),
+        platformOwnedReason: z.enum([
+            "insufficient_balance",
+            "chat_title",
+            "system_failure",
+            "provider_failure",
+            "missing_trusted_usage",
+        ]).nullable(),
+        availableAfter: z.number().int().nullable(),
+        createdAt: z.string(),
+    })),
+    nextBefore: z.string().nullable(),
+});
+export const mockCreditCheckoutRequestSchema = z.object({
+    orderId: z.uuid(),
+    priceId: z.string().min(1).max(255).optional(),
+    outcome: z.enum(["paid", "cancelled"]),
+}).strict();
+export const mockCreditCheckoutResultSchema = z.object({ status: z.enum(["paid", "cancelled"]) });