@greatwait/contracts 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/members.js

@@ -0,0 +1,223 @@
+import { z } from "./zod.js";
+import { projectIdSchema } from "./identifiers.js";
+import { API_UNUSED_RESPONSE_SCHEMA, defineOperations, } from "./operation-definitions.js";
+import { requiredIdempotencyRequestHeaderSchema } from "./protocol.js";
+const requestOnly = globalThis
+    .GREATWAIT_API_REQUEST_REGISTRY;
+const withoutExamples = globalThis
+    .GREATWAIT_RUNTIME_WITHOUT_EXAMPLES;
+const contractsOnly = globalThis
+    .GREATWAIT_RUNTIME_CONTRACTS_ONLY;
+/** Assignable roles on the included Clerk plan. Billing is not offered. */
+export const managedMemberRoleSchema = z.enum(["admin", "member"]);
+export const memberIdSchema = z.string().regex(/^mem_[0-9a-f]{26}$/u);
+export const invitationIdSchema = z.string().regex(/^inv_[0-9a-f]{26}$/u);
+export const memberViewSchema = z.strictObject({
+    id: memberIdSchema,
+    email: z.string().email(),
+    name: z.string(),
+    role: managedMemberRoleSchema,
+    projects: z.array(projectIdSchema),
+    allProjects: z.boolean(),
+    self: z.boolean(),
+});
+export const memberListSchema = z.strictObject({
+    data: z.array(memberViewSchema),
+});
+export const invitationViewSchema = z.strictObject({
+    id: invitationIdSchema,
+    email: z.string().email(),
+    role: managedMemberRoleSchema,
+    projects: z.array(projectIdSchema),
+    status: z.enum(["pending", "accepted", "revoked", "expired"]),
+});
+export const invitationListSchema = z.strictObject({
+    data: z.array(invitationViewSchema),
+});
+export const memberInviteRequestSchema = z.strictObject({
+    email: z.string().email(),
+    role: managedMemberRoleSchema,
+    projects: z.array(projectIdSchema),
+});
+export const memberRoleRequestSchema = z.strictObject({
+    role: managedMemberRoleSchema,
+});
+export const memberRemovalRequestSchema = z.strictObject({
+    confirmed: z.literal(true),
+});
+export const memberActionSchema = z.strictObject({
+    completed: z.literal(true),
+    id: z.union([memberIdSchema, invitationIdSchema]),
+    project: projectIdSchema.optional(),
+});
+const member = {
+    id: "mem_0123456789abcdef0123456789",
+    email: "teammate@example.com",
+    name: "Teammate",
+    role: "member",
+    projects: ["proj_01h8xyz9k2m4n6p8r0t2v4w6y8"],
+    allProjects: false,
+    self: false,
+};
+const invitation = {
+    id: "inv_0123456789abcdef0123456789",
+    email: "teammate@example.com",
+    role: "member",
+    projects: member.projects,
+    status: "pending",
+};
+const common = {
+    creates: false,
+    idempotent: true,
+    principals: ["session", "oauth"],
+    scopes: ["members:manage"],
+    surfaces: ["api", "mock"],
+    problems: [
+        "invalid_request",
+        "not_found",
+        "state_conflict",
+        "service_unavailable",
+        "capability_not_configured",
+    ],
+    sessionAuthority: "organization",
+};
+const write = {
+    ...common,
+    mutates: true,
+    problems: [...common.problems, "idempotency_key_reused"],
+    requestHeaders: requiredIdempotencyRequestHeaderSchema,
+    response: requestOnly ? API_UNUSED_RESPONSE_SCHEMA : memberActionSchema,
+    example: withoutExamples ? {} : { completed: true, id: member.id },
+    mcp: { kind: "tool", destructive: false, openWorld: true },
+};
+export const MEMBER_OPERATIONS = defineOperations([
+    {
+        ...common,
+        id: "members.list",
+        method: "GET",
+        path: "/v1/organization/members",
+        mutates: false,
+        response: requestOnly ? API_UNUSED_RESPONSE_SCHEMA : memberListSchema,
+        example: withoutExamples ? {} : { data: [member] },
+        mcp: { kind: "tool", destructive: false, openWorld: false },
+        summary: requestOnly ? "" : "List organization members and project access",
+        description: contractsOnly
+            ? ""
+            : "An administrator lists current members. Members cannot enumerate or manage their colleagues. OAuth requires current administrator membership and explicit members:manage consent; API keys cannot manage people.",
+    },
+    {
+        ...common,
+        id: "invitations.list",
+        method: "GET",
+        path: "/v1/organization/invitations",
+        mutates: false,
+        response: requestOnly ? API_UNUSED_RESPONSE_SCHEMA : invitationListSchema,
+        example: withoutExamples ? {} : { data: [invitation] },
+        mcp: { kind: "tool", destructive: false, openWorld: false },
+        summary: requestOnly ? "" : "List organization invitations",
+        description: contractsOnly
+            ? ""
+            : "Lists invitations with current pending, accepted, revoked or expired status. No invitation ticket is returned.",
+    },
+    {
+        ...write,
+        id: "invitations.create",
+        creates: true,
+        method: "POST",
+        path: "/v1/organization/invitations",
+        request: memberInviteRequestSchema,
+        response: requestOnly ? API_UNUSED_RESPONSE_SCHEMA : invitationViewSchema,
+        example: withoutExamples ? {} : invitation,
+        requestExample: withoutExamples
+            ? {}
+            : {
+                email: invitation.email,
+                role: invitation.role,
+                projects: invitation.projects,
+            },
+        summary: requestOnly ? "" : "Invite a teammate to selected projects",
+        description: contractsOnly
+            ? ""
+            : "Sends a Clerk organization invitation as admin or member, with the selected project access. No seat pricing or product member limit applies. Admins have access to every project.",
+    },
+    {
+        ...write,
+        id: "invitations.resend",
+        example: withoutExamples ? {} : { completed: true, id: invitation.id },
+        method: "POST",
+        path: "/v1/organization/invitations/{invitationId}/resend",
+        request: z.strictObject({}),
+        requestExample: withoutExamples ? {} : {},
+        summary: requestOnly ? "" : "Resend a pending invitation",
+        description: contractsOnly
+            ? ""
+            : "Revokes the previous ticket before sending a replacement for the same role and selected projects. Accepted, revoked or expired invitations cannot be resent.",
+    },
+    {
+        ...write,
+        id: "invitations.revoke",
+        example: withoutExamples ? {} : { completed: true, id: invitation.id },
+        method: "POST",
+        path: "/v1/organization/invitations/{invitationId}/revoke",
+        request: memberRemovalRequestSchema,
+        requestExample: withoutExamples ? {} : { confirmed: true },
+        mcp: { kind: "tool", destructive: true, openWorld: true },
+        summary: requestOnly ? "" : "Revoke a pending invitation",
+        description: contractsOnly
+            ? ""
+            : "Requires explicit confirmation. The outstanding ticket no longer grants organization or project access.",
+    },
+    {
+        ...write,
+        id: "members.role",
+        method: "PATCH",
+        path: "/v1/organization/members/{memberId}",
+        request: memberRoleRequestSchema,
+        requestExample: withoutExamples ? {} : { role: "member" },
+        mcp: { kind: "tool", destructive: true, openWorld: true },
+        summary: requestOnly ? "" : "Change a member's role",
+        description: contractsOnly
+            ? ""
+            : "An administrator changes another person's role. Self role changes and demoting the last administrator are refused, including concurrent requests. Existing sessions and grants are narrowed on their next request.",
+    },
+    {
+        ...write,
+        id: "members.remove",
+        method: "POST",
+        path: "/v1/organization/members/{memberId}/remove",
+        request: memberRemovalRequestSchema,
+        requestExample: withoutExamples ? {} : { confirmed: true },
+        mcp: { kind: "tool", destructive: true, openWorld: true },
+        summary: requestOnly ? "" : "Remove an organization member",
+        description: contractsOnly
+            ? ""
+            : "Requires explicit confirmation. Removing the last administrator or oneself is refused. Subsequent sessions and grants lose access; organization-owned API keys remain valid and may be revoked separately.",
+    },
+    {
+        ...write,
+        id: "projectmembers.add",
+        method: "PUT",
+        path: "/v1/projects/{projectId}/members/{memberId}",
+        sessionAuthority: "headers",
+        request: z.strictObject({}),
+        requestExample: withoutExamples ? {} : {},
+        summary: requestOnly ? "" : "Add a member to a project",
+        description: contractsOnly
+            ? ""
+            : "A current administrator adds another organization member to an owned project. Foreign members and projects are indistinguishable from missing ones. No self addition.",
+    },
+    {
+        ...write,
+        id: "projectmembers.remove",
+        method: "POST",
+        path: "/v1/projects/{projectId}/members/{memberId}/remove",
+        sessionAuthority: "headers",
+        request: memberRemovalRequestSchema,
+        requestExample: withoutExamples ? {} : { confirmed: true },
+        mcp: { kind: "tool", destructive: true, openWorld: false },
+        summary: requestOnly ? "" : "Remove a member's project access",
+        description: contractsOnly
+            ? ""
+            : "Requires explicit confirmation. The member's existing sessions and OAuth grants lose access on the next request. Administrators retain access to every project; organization-owned API keys keep their single-project authority.",
+    },
+]);

package/dist/oauth.d.ts

@@ -414,6 +414,7 @@ export declare const consentPromptSchema: import("zod").ZodObject<{
         name: import("zod").ZodString;
     }, import("zod/v4/core").$strip>>;
     scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";
@@ -455,6 +456,7 @@ export declare const consentDecisionSchema: import("zod").ZodDiscriminatedUnion<
     }>;
     project: import("zod").ZodString;
     scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";
@@ -591,6 +593,7 @@ export declare const oauthGrantSchema: import("zod").ZodObject<{
     }>>;
     revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
     scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";
@@ -637,6 +640,7 @@ export declare const oauthGrantListSchema: import("zod").ZodObject<{
         }>>;
         revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
         scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+            "members:manage": "members:manage";
             "credentials:administer": "credentials:administer";
             "billing:write": "billing:write";
             "credentials:read": "credentials:read";
@@ -691,6 +695,7 @@ export declare const oauthGrantRevokedSchema: import("zod").ZodObject<{
         }>>;
         revokedAt: import("zod").ZodOptional<import("zod").ZodString>;
         scopes: import("zod").ZodArray<import("zod").ZodEnum<{
+            "members:manage": "members:manage";
             "credentials:administer": "credentials:administer";
             "billing:write": "billing:write";
             "credentials:read": "credentials:read";
@@ -742,6 +747,7 @@ export declare const authorizationServerMetadataSchema: import("zod").ZodObject<
     }>>;
     revocation_endpoint: import("zod").ZodURL;
     scopes_supported: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";
@@ -780,6 +786,7 @@ export declare const protectedResourceMetadataSchema: import("zod").ZodObject<{
     bearer_methods_supported: import("zod").ZodArray<import("zod").ZodLiteral<"header">>;
     resource: import("zod").ZodURL;
     scopes_supported: import("zod").ZodArray<import("zod").ZodEnum<{
+        "members:manage": "members:manage";
         "credentials:administer": "credentials:administer";
         "billing:write": "billing:write";
         "credentials:read": "credentials:read";

package/dist/operation-definitions.d.ts

@@ -1,9 +1,25 @@
 import type { OperationDefinition } from "./operations.js";
 /** Fail-closed response placeholder used by the hosted API's request-only registry. */
 export declare const API_UNUSED_RESPONSE_SCHEMA: import("zod").ZodNever;
-/** Keep registry ids precise without duplicating inferred Zod internals in every consumer declaration. */
+/**
+ * Keep registry ids precise without duplicating inferred Zod internals in every
+ * consumer declaration.
+ *
+ * The request schema is kept as well (W9-46): the generated client types each
+ * builder's body from it, and an entry declared here with only its id kept
+ * would leave that body `unknown` — the member and invitation commands took
+ * any object at all until this carried it.
+ */
 export declare function defineOperations<const T extends readonly OperationDefinition[]>(definitions: T): {
-    readonly [K in keyof T]: OperationDefinition & {
-        readonly id: T[K]["id"];
-    };
+    readonly [K in keyof T]: DefinedOperation<T[K]>;
 };
+type DefinedOperation<TEntry> = OperationDefinition & {
+    readonly id: TEntry extends {
+        readonly id: infer TId;
+    } ? TId : never;
+} & (TEntry extends {
+    readonly request: infer TRequest;
+} ? {
+    readonly request: TRequest;
+} : unknown);
+export {};

package/dist/operation-definitions.js

@@ -1,7 +1,15 @@
 import { never as neverSchema } from "zod";
 /** Fail-closed response placeholder used by the hosted API's request-only registry. */
 export const API_UNUSED_RESPONSE_SCHEMA = neverSchema();
-/** Keep registry ids precise without duplicating inferred Zod internals in every consumer declaration. */
+/**
+ * Keep registry ids precise without duplicating inferred Zod internals in every
+ * consumer declaration.
+ *
+ * The request schema is kept as well (W9-46): the generated client types each
+ * builder's body from it, and an entry declared here with only its id kept
+ * would leave that body `unknown` — the member and invitation commands took
+ * any object at all until this carried it.
+ */
 export function defineOperations(definitions) {
     return definitions;
 }

package/dist/operational-config.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The single numeric owner for deployment-governed timer, timeout and retry
+ * configuration. Values preserve the accepted policy and measured W9 timing
+ * budgets; this leaf imports no schemas, application code or database runtime.
+ * Change through a reviewed deployment. Retrying a callback, funding operation
+ * or idempotency receipt is a public correctness promise, so organizations may
+ * not override these values. Original owner modules keep compatible exports.
+ */
+export declare const OPERATIONAL_TIMING: Readonly<{
+    projectBillingConflictRetryCount: 4;
+    projectBillingConflictRetryBaseMs: 250;
+    billingNoticeBackoffBaseMs: 60000;
+    automaticFundingBackoffBaseMs: 60000;
+    controlPlaneBackoffBaseMs: 10;
+    postgresConnectionAcquisitionMs: 2900;
+    postgresLockMs: 2000;
+    postgresStatementMs: 2900;
+    postgresTransactionBudgetMs: 2900;
+    postgresTransactionMaximumMs: 2999;
+    apiMutationStatementMs: 5000;
+    apiMutationBudgetMs: 5000;
+    apiMutationMaximumMs: 5000;
+    controlPlaneWriteStatementMs: 5000;
+    controlPlaneWriteBudgetMs: 5000;
+    dispatchHedgeAfterMs: 400;
+    dispatchHedgeThirdLegMs: 1200;
+    apiHedgeAfterMs: 300;
+    authorizationReplayDelaysMs: readonly [500, 1500, 4000];
+    claimProbeCount: 3;
+    claimReclaimCount: 3;
+    claimReclaimWindowMs: 1200;
+    controlPlaneBackoffCeilingMs: 200;
+    controlPlaneConnectMs: 5000;
+    conclusionReplayDelaysMs: readonly [250, 1000, 2000, 4000];
+    hostFullRetryMs: 1000;
+    deliveryRetryBaseMs: readonly [2000, 5000, 15000, 60000];
+    deliveryRetryAfterMaximumMs: 3600000;
+    wakeReceiptRetryMs: 5000;
+    wakeReceiptRecoveryLifetimeMs: number;
+    repairOverdueGraceSeconds: 10;
+    admissionWindowMs: 1000;
+    admissionLookaheadMs: 60000;
+    admissionHedgeAfterMs: 250;
+    admissionRpcBudgetMs: 2999;
+    unreachableRetryMs: 5000;
+    heldResponseStepMarginMs: 20000;
+    sendLeaseMarginSeconds: 12;
+    sendSettlementReserveMs: 7000;
+    exhaustedClaimRetryMs: 250;
+    retentionCadenceMs: number;
+    retentionBacklogCadenceMs: number;
+    retentionRetryHandoffCount: 5;
+    timerSignalRetryDelaysMs: readonly number[];
+    dispatchWarmHorizonMs: 10000;
+    sdkAutoRetryCount: 3;
+    sdkAutoRetryBaseMs: 250;
+    sdkAutoRetryMaximumWaitMs: 30000;
+    callbackMiddlewareLeaseMs: 30000;
+    automaticFundingSuccessCooldownMs: number;
+    automaticFundingClaimLeaseMs: number;
+    automaticFundingBackoffMaximumMs: number;
+    providerCreateFenceMs: number;
+    fundingUnresolvedAfterMs: number;
+    fundingRepairMs: number;
+    fundingActionRequiredRepairMs: number;
+    fundingDisputeRepairMs: number;
+    billingNoticeBackoffMaximumMs: 86400000;
+    billingNoticeClaimMaximumMs: number;
+    billingNoticeRetryMaximumMs: number;
+    billingNoticeCatchUpRetryCount: 5;
+    billingNoticeClaimSeconds: number;
+    fundingDiscoveryClaimMs: number;
+    fundingDiscoveryRetryMaximumMs: number;
+    fundingDiscoveryClaimMaximumMs: number;
+    fundingAbandonedAfterMs: number;
+    checkoutDiscoverySkewSeconds: 60;
+    checkoutDiscoveryWindowSeconds: number;
+    fundingQuoteLifetimeMs: number;
+    automaticFundingPreviewLifetimeMs: number;
+    testSinkRefreshMs: 3000;
+    payloadLintDelayMs: 250;
+    payloadParseBudgetMs: 50;
+    dashboardQueryStaleMs: 30000;
+    forecastRefreshFloorMs: 30000;
+    forecastRefreshMaximumMs: 300000;
+    forecastCoverageSlackMs: 120000;
+}>;
+export type OperationalTimingKey = keyof typeof OPERATIONAL_TIMING;
+export declare const OPERATIONAL_TIMING_ENFORCEMENT: Readonly<Record<OperationalTimingKey, readonly string[]>>;
+/** Catalog metadata derives its defaults from the numeric owner above. */
+export declare const OPERATIONAL_TIMING_CATALOG: readonly Readonly<{
+    key: "operational.projectBillingConflictRetryCount" | "operational.projectBillingConflictRetryBaseMs" | "operational.billingNoticeBackoffBaseMs" | "operational.automaticFundingBackoffBaseMs" | "operational.controlPlaneBackoffBaseMs" | "operational.postgresConnectionAcquisitionMs" | "operational.postgresLockMs" | "operational.postgresStatementMs" | "operational.postgresTransactionBudgetMs" | "operational.postgresTransactionMaximumMs" | "operational.apiMutationStatementMs" | "operational.apiMutationBudgetMs" | "operational.apiMutationMaximumMs" | "operational.controlPlaneWriteStatementMs" | "operational.controlPlaneWriteBudgetMs" | "operational.dispatchHedgeAfterMs" | "operational.dispatchHedgeThirdLegMs" | "operational.apiHedgeAfterMs" | "operational.authorizationReplayDelaysMs" | "operational.claimProbeCount" | "operational.claimReclaimCount" | "operational.claimReclaimWindowMs" | "operational.controlPlaneBackoffCeilingMs" | "operational.controlPlaneConnectMs" | "operational.conclusionReplayDelaysMs" | "operational.hostFullRetryMs" | "operational.deliveryRetryBaseMs" | "operational.deliveryRetryAfterMaximumMs" | "operational.wakeReceiptRetryMs" | "operational.wakeReceiptRecoveryLifetimeMs" | "operational.repairOverdueGraceSeconds" | "operational.admissionWindowMs" | "operational.admissionLookaheadMs" | "operational.admissionHedgeAfterMs" | "operational.admissionRpcBudgetMs" | "operational.unreachableRetryMs" | "operational.heldResponseStepMarginMs" | "operational.sendLeaseMarginSeconds" | "operational.sendSettlementReserveMs" | "operational.exhaustedClaimRetryMs" | "operational.retentionCadenceMs" | "operational.retentionBacklogCadenceMs" | "operational.retentionRetryHandoffCount" | "operational.timerSignalRetryDelaysMs" | "operational.dispatchWarmHorizonMs" | "operational.sdkAutoRetryCount" | "operational.sdkAutoRetryBaseMs" | "operational.sdkAutoRetryMaximumWaitMs" | "operational.callbackMiddlewareLeaseMs" | "operational.automaticFundingSuccessCooldownMs" | "operational.automaticFundingClaimLeaseMs" | "operational.automaticFundingBackoffMaximumMs" | "operational.providerCreateFenceMs" | "operational.fundingUnresolvedAfterMs" | "operational.fundingRepairMs" | "operational.fundingActionRequiredRepairMs" | "operational.fundingDisputeRepairMs" | "operational.billingNoticeBackoffMaximumMs" | "operational.billingNoticeClaimMaximumMs" | "operational.billingNoticeRetryMaximumMs" | "operational.billingNoticeCatchUpRetryCount" | "operational.billingNoticeClaimSeconds" | "operational.fundingDiscoveryClaimMs" | "operational.fundingDiscoveryRetryMaximumMs" | "operational.fundingDiscoveryClaimMaximumMs" | "operational.fundingAbandonedAfterMs" | "operational.checkoutDiscoverySkewSeconds" | "operational.checkoutDiscoveryWindowSeconds" | "operational.fundingQuoteLifetimeMs" | "operational.automaticFundingPreviewLifetimeMs" | "operational.testSinkRefreshMs" | "operational.payloadLintDelayMs" | "operational.payloadParseBudgetMs" | "operational.dashboardQueryStaleMs" | "operational.forecastRefreshFloorMs" | "operational.forecastRefreshMaximumMs" | "operational.forecastCoverageSlackMs";
+    default: number | readonly number[] | readonly [500, 1500, 4000] | readonly [250, 1000, 2000, 4000] | readonly [2000, 5000, 15000, 60000];
+    unit: "count" | "seconds" | "milliseconds";
+    scope: "deployment";
+    permittedLayers: readonly ["deployment"];
+    visibility: "operator";
+    changeProcedure: "Reviewed deployment; preserve callback, retry, funding and receipt compatibility";
+    rationale: "Retain the existing measured or copied operating policy; the enforcement owner documents its evidence";
+    enforcement: readonly string[];
+}>[];