@greatwait/contracts 0.1.0-alpha.7 → 0.2.0

package/dist/project-notifications.js

@@ -0,0 +1,236 @@
+import { z } from "./zod.js";
+import { environmentKindSchema } from "./authority.js";
+import { callbackSigningKeyIdSchema, occurrenceIdSchema, projectIdSchema, scheduleIdSchema, } from "./identifiers.js";
+import { memberIdSchema } from "./members.js";
+import { timestampSchema } from "./time.js";
+import { pageRequestSchema, requiredIdempotencyRequestHeaderSchema, } from "./protocol.js";
+import { API_UNUSED_RESPONSE_SCHEMA, defineOperations, } from "./operation-definitions.js";
+/** Per-project/environment preferences. Billing-safety notices are separate. */
+export const notificationEmailRecipientsSchema = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("admins") }),
+    z.strictObject({
+        kind: z.literal("members"),
+        memberIds: z
+            .array(memberIdSchema)
+            .min(1)
+            .max(100)
+            .refine((ids) => new Set(ids).size === ids.length, "members must be unique"),
+    }),
+]);
+export const notificationEmailSettingsSchema = z.strictObject({
+    enabled: z.boolean(),
+    recipients: notificationEmailRecipientsSchema,
+    scheduleKinds: z.enum(["both", "one-shot", "recurring"]),
+});
+export const statusWebhookEventSchema = z.enum(["failed"]);
+export const statusWebhookConfigurationSchema = z.strictObject({
+    url: z.string().url().max(2_048),
+    events: z
+        .array(statusWebhookEventSchema)
+        .min(1)
+        .max(1)
+        .refine((events) => new Set(events).size === events.length, "events must be unique"),
+});
+export const projectNotificationSettingsSchema = z.strictObject({
+    project: projectIdSchema,
+    environmentKind: environmentKindSchema,
+    revision: z.number().int().positive(),
+    email: notificationEmailSettingsSchema,
+    statusWebhook: statusWebhookConfigurationSchema
+        .extend({
+        signingKey: z.strictObject({ id: callbackSigningKeyIdSchema }).optional(),
+        revision: z.number().int().positive(),
+    })
+        .optional(),
+});
+export const projectNotificationSettingsUpdateRequestSchema = z
+    .strictObject({
+    expectedRevision: z.number().int().positive(),
+    email: notificationEmailSettingsSchema.optional(),
+    statusWebhook: statusWebhookConfigurationSchema.nullable().optional(),
+})
+    .refine((request) => request.email !== undefined || request.statusWebhook !== undefined, "choose settings to change");
+export const statusSigningKeyRequestSchema = z.strictObject({
+    expectedRevision: z.number().int().positive(),
+});
+export const statusSigningKeyCreatedSchema = z.strictObject({
+    settings: projectNotificationSettingsSchema,
+    keyId: callbackSigningKeyIdSchema,
+    secret: z.string().min(1),
+    shownOnce: z.literal(true),
+});
+/** Safe notification payload: no customer request or response content. */
+export const statusWebhookPayloadSchema = z.object({
+    version: z.literal("2026-10-08"),
+    eventId: z.string().min(1).max(255),
+    type: statusWebhookEventSchema,
+    projectId: projectIdSchema,
+    environmentKind: environmentKindSchema,
+    scheduleId: scheduleIdSchema,
+    occurrenceId: occurrenceIdSchema,
+    occurredAt: timestampSchema,
+    outcomeOrigin: z.enum(["platform", "customer"]),
+    diagnostic: z.string().max(512).optional(),
+    statusCode: z.number().int().min(100).max(599).optional(),
+    pause: z.unknown().optional(),
+});
+export const statusWebhookDeliverySchema = z.strictObject({
+    id: z.string().min(1).max(255),
+    event: statusWebhookEventSchema,
+    schedule: scheduleIdSchema,
+    occurrence: occurrenceIdSchema,
+    occurredAt: timestampSchema,
+    url: z.string().url(),
+    state: z.enum(["pending", "delivering", "delivered", "failed", "suppressed"]),
+    attempts: z.number().int().nonnegative(),
+    nextAttemptAt: timestampSchema.optional(),
+    lastStatus: z.number().int().min(100).max(599).optional(),
+    lastError: z.string().max(128).optional(),
+});
+export const statusWebhookDeliveryPageSchema = z.strictObject({
+    data: z.array(statusWebhookDeliverySchema),
+    nextCursor: z.string().min(1).optional(),
+});
+const globals = globalThis;
+const settings = {
+    project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+    environmentKind: "live",
+    revision: 1,
+    email: {
+        enabled: true,
+        recipients: { kind: "admins" },
+        scheduleKinds: "both",
+    },
+};
+const common = {
+    creates: false,
+    principals: ["api-credential", "oauth", "session"],
+    sessionAuthority: "headers",
+    surfaces: ["api", "mock"],
+    problems: ["invalid_request", "not_found", "service_unavailable"],
+};
+export const PROJECT_NOTIFICATION_OPERATIONS = defineOperations([
+    {
+        ...common,
+        id: "projectnotifications.read",
+        method: "GET",
+        path: "/v1/projects/{projectId}/notification-settings",
+        idempotent: true,
+        mutates: false,
+        mcp: { kind: "tool", destructive: false, openWorld: false },
+        scopes: ["projects:read"],
+        response: globals.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : projectNotificationSettingsSchema,
+        example: globals.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES ? {} : settings,
+        summary: globals.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Read delivery notification settings",
+        description: globals.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Read the verified project and environment's email failure alerts and failure webhook preferences. Defaults are email on to current organization admins and both one-shot and recurring schedules. Every terminal failed occurrence creates a separate email for each eligible recipient. Signing secrets are absent. Manual redelivery does not repeat occurrence lifecycle events.",
+    },
+    {
+        ...common,
+        id: "projectnotifications.update",
+        method: "PATCH",
+        path: "/v1/projects/{projectId}/notification-settings",
+        idempotent: true,
+        mutates: true,
+        mcp: { kind: "tool", destructive: false, openWorld: true },
+        scopes: ["projects:administer"],
+        problems: [
+            ...common.problems,
+            "revision_conflict",
+            "idempotency_key_reused",
+            "rate_limited",
+        ],
+        requestHeaders: requiredIdempotencyRequestHeaderSchema,
+        request: projectNotificationSettingsUpdateRequestSchema,
+        requestExample: globals.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { expectedRevision: 1, email: settings.email },
+        response: globals.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : projectNotificationSettingsSchema,
+        example: globals.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { ...settings, revision: 2 },
+        summary: globals.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Update delivery notification settings",
+        description: globals.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "An admin updates this project's environment preferences at an expected revision. Selected recipients must be current organization members; arbitrary email addresses are not accepted. Null disables the status webhook. Changing URL or filters never reveals a signing secret. Mint the first key through the secure signing-key operation before webhook delivery starts. Failed means final unsuccessful settlement. Redelivery never repeats it. Failed-event webhook calls and their retries are free. Every failed occurrence is emailed separately; no summary window suppresses failures.",
+    },
+    {
+        ...common,
+        id: "projectnotifications.rotateSigningKey",
+        method: "POST",
+        path: "/v1/projects/{projectId}/notification-settings/status-signing-key",
+        idempotent: false,
+        mutates: true,
+        mcp: {
+            kind: "unavailable",
+            reason: "Minting or rotating returns a one-time signing secret. MCP has no negotiated secure-result channel that keeps it out of ordinary tool history. Configure preferences with projectnotifications_update, then use the dashboard or an authenticated REST/SDK/CLI client for the secret.",
+        },
+        scopes: ["projects:administer"],
+        problems: [
+            ...common.problems,
+            "revision_conflict",
+            "state_conflict",
+            "capability_not_configured",
+        ],
+        request: statusSigningKeyRequestSchema,
+        requestExample: globals.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { expectedRevision: 1 },
+        response: globals.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : statusSigningKeyCreatedSchema,
+        example: globals.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {
+                settings: {
+                    ...settings,
+                    revision: 2,
+                    statusWebhook: {
+                        url: "https://hooks.example.com/status",
+                        events: ["failed"],
+                        revision: 2,
+                        signingKey: { id: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" },
+                    },
+                },
+                keyId: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                secret: "ptsk_live_<the-one-time-status-secret>",
+                shownOnce: true,
+            },
+        summary: globals.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Mint or rotate the status webhook signing key",
+        description: globals.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "An admin mints the first key or replaces the current key for an already configured status webhook at an expected revision. The secret appears only in this successful response and cannot be read back. A lost response requires a fresh revision read and another rotation. Queued deliveries using the replaced signing key are suppressed. The request is not automatically replayable; stale retries are refused. The signature covers the exact emitted body bytes.",
+    },
+    {
+        ...common,
+        id: "statusdeliveries.list",
+        method: "GET",
+        path: "/v1/projects/{projectId}/status-deliveries",
+        idempotent: true,
+        mutates: false,
+        mcp: { kind: "tool", destructive: false, openWorld: false },
+        scopes: ["occurrences:read"],
+        query: pageRequestSchema,
+        response: globals.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : statusWebhookDeliveryPageSchema,
+        example: globals.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES ? {} : { data: [] },
+        summary: globals.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "List failure webhook deliveries",
+        description: globals.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Read the verified project and environment's failure delivery trail, including retry state and actual outbound calls. Failed events and every retry are free. Status delivery failures never create another notification or change the customer's schedule outcome. Customer callback contents and signing secrets are absent.",
+    },
+]);

package/dist/scheduling.js

@@ -1407,10 +1407,11 @@ export const scheduleRequestSchema = z
      *
      * Two schedules with different keys are paced independently, so one key's
      * herd does not delay another's work. It is a label and a lane and nothing
-     * more: it cannot widen the authority tuple, cannot select a different
-     * database shard or timer actor, and cannot raise anybody's rate — the
-     * lanes share the project's ceiling, so minting more keys divides the same
-     * budget rather than multiplying it.
+     * more: it cannot widen the authority tuple or select a different database
+     * shard or timer actor. Each key is paced on its own, but every lane that
+     * delivers to the same receiver host shares that host's pacing, so more keys
+     * never raise the rate any one receiver sees; the plan's
+     * `partitionKeyCeiling` bounds how many distinct keys an organization holds.
      *
      * **Fixed once the schedule exists.** A replace may carry the key it read
      * back or omit it to preserve the stored value. Adding, changing, or

package/dist/workspace.d.ts

@@ -9,8 +9,8 @@ import { z } from "./zod.js";
  */
 export declare const WORKSPACE_LAYERS: readonly ["contract", "platform", "domain", "application", "adapter", "test-support"];
 export declare const workspaceLayerSchema: import("zod").ZodEnum<{
-    contract: "contract";
     platform: "platform";
+    contract: "contract";
     domain: "domain";
     application: "application";
     adapter: "adapter";
@@ -19,8 +19,8 @@ export declare const workspaceLayerSchema: import("zod").ZodEnum<{
 export type WorkspaceLayer = z.infer<typeof workspaceLayerSchema>;
 export declare const workspaceIdentitySchema: import("zod").ZodObject<{
     layer: import("zod").ZodEnum<{
-        contract: "contract";
         platform: "platform";
+        contract: "contract";
         domain: "domain";
         application: "application";
         adapter: "adapter";
@@ -39,16 +39,16 @@ export type ScaffoldVersion = z.infer<typeof scaffoldVersionSchema>;
 /** Shape of the scaffold description an adapter reads from the application. */
 export declare const workspaceScaffoldSchema: import("zod").ZodObject<{
     dependsOn: import("zod").ZodArray<import("zod").ZodEnum<{
-        contract: "contract";
         platform: "platform";
+        contract: "contract";
         domain: "domain";
         application: "application";
         adapter: "adapter";
         "test-support": "test-support";
     }>>;
     layer: import("zod").ZodEnum<{
-        contract: "contract";
         platform: "platform";
+        contract: "contract";
         domain: "domain";
         application: "application";
         adapter: "adapter";

package/generated/v1/examples/projectnotifications.read.response.json

@@ -0,0 +1,12 @@
+{
+  "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+  "environmentKind": "live",
+  "revision": 1,
+  "email": {
+    "enabled": true,
+    "recipients": {
+      "kind": "admins"
+    },
+    "scheduleKinds": "both"
+  }
+}

package/generated/v1/examples/projectnotifications.rotateSigningKey.request.json

@@ -0,0 +1,3 @@
+{
+  "expectedRevision": 1
+}

package/generated/v1/examples/projectnotifications.rotateSigningKey.response.json

@@ -0,0 +1,25 @@
+{
+  "settings": {
+    "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+    "environmentKind": "live",
+    "revision": 2,
+    "email": {
+      "enabled": true,
+      "recipients": {
+        "kind": "admins"
+      },
+      "scheduleKinds": "both"
+    },
+    "statusWebhook": {
+      "url": "https://hooks.example.com/status",
+      "events": ["failed"],
+      "signingKey": {
+        "id": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8"
+      },
+      "revision": 2
+    }
+  },
+  "keyId": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+  "secret": "ptsk_live_<the-one-time-status-secret>",
+  "shownOnce": true
+}

package/generated/v1/examples/projectnotifications.update.request.json

@@ -0,0 +1,10 @@
+{
+  "expectedRevision": 1,
+  "email": {
+    "enabled": true,
+    "recipients": {
+      "kind": "admins"
+    },
+    "scheduleKinds": "both"
+  }
+}

package/generated/v1/examples/projectnotifications.update.response.json

@@ -0,0 +1,12 @@
+{
+  "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+  "environmentKind": "live",
+  "revision": 2,
+  "email": {
+    "enabled": true,
+    "recipients": {
+      "kind": "admins"
+    },
+    "scheduleKinds": "both"
+  }
+}

package/generated/v1/examples/statusdeliveries.list.response.json

@@ -0,0 +1,3 @@
+{
+  "data": []
+}

package/generated/v1/manifest.json

@@ -124,6 +124,11 @@
     "examples/projectmembers.add.response.json",
     "examples/projectmembers.remove.request.json",
     "examples/projectmembers.remove.response.json",
+    "examples/projectnotifications.read.response.json",
+    "examples/projectnotifications.rotateSigningKey.request.json",
+    "examples/projectnotifications.rotateSigningKey.response.json",
+    "examples/projectnotifications.update.request.json",
+    "examples/projectnotifications.update.response.json",
     "examples/projects.archive.request.json",
     "examples/projects.archive.response.json",
     "examples/projects.create.request.json",
@@ -144,6 +149,7 @@
     "examples/schedules.resume.response.json",
     "examples/sinkdeliveries.list.response.json",
     "examples/sinkdeliveries.read.response.json",
+    "examples/statusdeliveries.list.response.json",
     "examples/testsinks.configure.request.json",
     "examples/testsinks.configure.response.json",
     "examples/testsinks.create.request.json",
@@ -310,6 +316,12 @@
     "schemas/projectmembers.remove.request-headers.json",
     "schemas/projectmembers.remove.request.json",
     "schemas/projectmembers.remove.response.json",
+    "schemas/projectnotifications.read.response.json",
+    "schemas/projectnotifications.rotateSigningKey.request.json",
+    "schemas/projectnotifications.rotateSigningKey.response.json",
+    "schemas/projectnotifications.update.request-headers.json",
+    "schemas/projectnotifications.update.request.json",
+    "schemas/projectnotifications.update.response.json",
     "schemas/projects.archive.request-headers.json",
     "schemas/projects.archive.request.json",
     "schemas/projects.archive.response-headers.json",
@@ -350,6 +362,8 @@
     "schemas/sinkdeliveries.list.query.json",
     "schemas/sinkdeliveries.list.response.json",
     "schemas/sinkdeliveries.read.response.json",
+    "schemas/statusdeliveries.list.query.json",
+    "schemas/statusdeliveries.list.response.json",
     "schemas/testsinks.configure.request.json",
     "schemas/testsinks.configure.response.json",
     "schemas/testsinks.create.request.json",
@@ -445,6 +459,9 @@
     "snippets/organizations.restore.json",
     "snippets/projectmembers.add.json",
     "snippets/projectmembers.remove.json",
+    "snippets/projectnotifications.read.json",
+    "snippets/projectnotifications.rotateSigningKey.json",
+    "snippets/projectnotifications.update.json",
     "snippets/projects.archive.json",
     "snippets/projects.create.json",
     "snippets/projects.delete.json",
@@ -460,6 +477,7 @@
     "snippets/schedules.resume.json",
     "snippets/sinkdeliveries.list.json",
     "snippets/sinkdeliveries.read.json",
+    "snippets/statusdeliveries.list.json",
     "snippets/testsinks.configure.json",
     "snippets/testsinks.create.json",
     "snippets/testsinks.delete.json",
@@ -808,6 +826,98 @@
       "sessionAuthority": "headers",
       "surfaces": ["api", "mock"]
     },
+    {
+      "id": "projectnotifications.read",
+      "method": "GET",
+      "mutates": false,
+      "path": "/v1/projects/{projectId}/notification-settings",
+      "principals": ["api-credential", "oauth", "session"],
+      "problems": [
+        "authentication_required",
+        "capability_not_configured",
+        "credential_expired",
+        "credential_revoked",
+        "invalid_request",
+        "not_found",
+        "project_archived",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["projects:read"],
+      "sessionAuthority": "headers",
+      "surfaces": ["api", "mock"]
+    },
+    {
+      "id": "projectnotifications.update",
+      "method": "PATCH",
+      "mutates": true,
+      "path": "/v1/projects/{projectId}/notification-settings",
+      "principals": ["api-credential", "oauth", "session"],
+      "problems": [
+        "authentication_required",
+        "capability_not_configured",
+        "credential_expired",
+        "credential_revoked",
+        "idempotency_key_reused",
+        "invalid_request",
+        "not_found",
+        "project_archived",
+        "rate_limited",
+        "revision_conflict",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["projects:administer"],
+      "sessionAuthority": "headers",
+      "surfaces": ["api", "mock"]
+    },
+    {
+      "id": "projectnotifications.rotateSigningKey",
+      "method": "POST",
+      "mutates": true,
+      "path": "/v1/projects/{projectId}/notification-settings/status-signing-key",
+      "principals": ["api-credential", "oauth", "session"],
+      "problems": [
+        "authentication_required",
+        "capability_not_configured",
+        "credential_expired",
+        "credential_revoked",
+        "invalid_request",
+        "not_found",
+        "project_archived",
+        "rate_limited",
+        "revision_conflict",
+        "scope_missing",
+        "service_unavailable",
+        "state_conflict"
+      ],
+      "scopes": ["projects:administer"],
+      "sessionAuthority": "headers",
+      "surfaces": ["api", "mock"]
+    },
+    {
+      "id": "statusdeliveries.list",
+      "method": "GET",
+      "mutates": false,
+      "path": "/v1/projects/{projectId}/status-deliveries",
+      "principals": ["api-credential", "oauth", "session"],
+      "problems": [
+        "authentication_required",
+        "capability_not_configured",
+        "credential_expired",
+        "credential_revoked",
+        "invalid_request",
+        "not_found",
+        "project_archived",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["occurrences:read"],
+      "sessionAuthority": "headers",
+      "surfaces": ["api", "mock"]
+    },
     {
       "id": "organizations.lifecycle",
       "method": "GET",