@greatwait/contracts 0.2.0 → 0.2.2

package/dist/operations.js

@@ -10,7 +10,7 @@ import { callbackEndpointCreatedSchema, callbackEndpointEnsuredSchema, callbackE
 import { FORECAST_WINDOW_VERSION, forecastRequestSchema, forecastSchema, forecastRequestHeadersSchema, forecastWindowsSchema, } from "./forecast.js";
 import { usageRequestSchema, usageSchema } from "./usage.js";
 import { deliveryTimingSummarySchema } from "./timing.js";
-import { billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingFundingViewSchema, billingNoticePageSchema, billingNotificationSettingsSchema, billingNotificationSettingsUpdateRequestSchema, billingLedgerPageSchema, billingLedgerRequestSchema, billingBudgetUpdateRequestHeadersSchema, billingBudgetUpdateRequestSchema, billingBudgetUpdateResponseSchema, billingPurchaseRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRefundRequestViewSchema, billingSummarySchema, projectBillingStateSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, projectBillingChangeRequestSchema, billingPortalSchema, billingInvoiceListSchema, billingPaymentHistoryPageSchema, billingInvoiceHistoryPageSchema, billingPaymentMethodSchema, billingPaymentMethodSetupRequestSchema, billingPaymentMethodConfirmRequestSchema, billingPaymentMethodRemoveRequestSchema, } from "./billing.js";
+import { billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingFundingViewSchema, billingNoticePageSchema, billingNotificationSettingsSchema, billingNotificationSettingsUpdateRequestSchema, billingLedgerPageSchema, billingLedgerRequestSchema, billingBudgetUpdateRequestHeadersSchema, billingBudgetUpdateRequestSchema, billingBudgetUpdateResponseSchema, billingPurchaseRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRefundRequestViewSchema, billingSummarySchema, billingPromotionsSchema, billingRedeemRequestSchema, billingRedeemResponseSchema, projectBillingStateSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, projectBillingChangeRequestSchema, billingPortalSchema, billingInvoiceListSchema, billingPaymentHistoryPageSchema, billingInvoiceHistoryPageSchema, billingPaymentMethodSchema, billingPaymentMethodSetupRequestSchema, billingPaymentMethodConfirmRequestSchema, billingPaymentMethodRemoveRequestSchema, } from "./billing.js";
 import { conditionalRequestHeaderSchema, idempotencyReplayResponseHeaderSchema, idempotencyRequestHeaderSchema, historyPageRequestSchema, pageRequestSchema, scheduleListRequestSchema, replayedResponseHeaderSchema, requiredConditionalRequestHeaderSchema, requiredIdempotencyRequestHeaderSchema, versionResponseHeaderSchema, } from "./protocol.js";
 import { oauthGrantListSchema, oauthGrantRevokedSchema } from "./oauth.js";
 import { credentialCreatedSchema, credentialPageSchema, credentialRequestSchema, credentialRevokedSchema, credentialRotatedSchema, credentialRotationRequestSchema, } from "./secrets.js";
@@ -76,6 +76,24 @@ const PROJECT_BILLING_QUOTE_EXAMPLE = {
     effectiveAt: "2026-09-10T12:00:00.000Z",
     formerIncludedWillBlock: false,
 };
+const BILLING_PROMOTIONS_EXAMPLE = {
+    grants: [
+        {
+            benefit: {
+                amount: { currency: "USD", microdollars: "10000000", scale: 6 },
+                kind: "credit",
+            },
+            endsAt: "2026-12-08T12:00:00.000Z",
+            id: "grn_01hzy3v8k2m9q4r6t7w8x9y0za",
+            source: "code",
+            startsAt: "2026-09-09T12:00:00.000Z",
+            state: "active",
+        },
+    ],
+    perks: [],
+    projectCapacity: { complimentary: 0, included: 1, paid: 0 },
+    restrictions: [],
+};
 const BILLING_SUMMARY_EXAMPLE = {
     activation: {
         boundary: "2026-09-01T00:00:00.000Z",
@@ -2427,6 +2445,80 @@ export const OPERATIONS = [
             : "Read exact execution-credit state",
         surfaces: ["api", "mock"],
     },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Lists the verified organization's launch promotions: each promotional credit grant, complimentary project slot, perk and project-subscription discount, whether it came from an operator or a redeemed code, and when it ends or was revoked. Also reports effective project capacity by source and any restriction that applies. Promotional credit balances by kind are on billing.summary. Promotional value has no cash value, is never refunded and cannot move to another organization or product.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : BILLING_PROMOTIONS_EXAMPLE,
+        environments: ["live"],
+        id: "billing.promotions",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/billing/promotions",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["service_unavailable", "test_to_live_escalation"],
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : billingPromotionsSchema,
+        scopes: ["usage:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "List promotions and complimentary grants",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: true,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Redeems one promotion code for the verified organization, with the billing owner's explicit confirmation. A code carries one benefit: promotional execution credit that expires and is spent before purchased credit, a complimentary slot for a named project that never becomes a paid subscription, a perk, or a discount on the project subscription shown in the next project quote. Every code that cannot be redeemed — unknown, ended, used up, not for this organization, or not combinable with a benefit already held — receives the same not_found answer; repeated refusals are throttled with rate_limited. The Idempotency-Key makes retries return the original grant. Nothing is charged and no payment method is needed.",
+        environments: ["live"],
+        id: "billing.redeem",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/billing/promotions/redeem",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "idempotency_key_reused",
+            "invalid_request",
+            "not_found",
+            "rate_limited",
+            "service_unavailable",
+            "state_conflict",
+            "test_to_live_escalation",
+        ],
+        request: billingRedeemRequestSchema,
+        requestExample: globalThis
+            .GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { code: "LAUNCH-2026", confirmed: true },
+        requestHeaders: requiredIdempotencyRequestHeaderSchema,
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : billingRedeemResponseSchema,
+        ...(globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? {}
+            : { responseHeaders: idempotencyReplayResponseHeaderSchema }),
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {
+                grant: BILLING_PROMOTIONS_EXAMPLE.grants[0],
+                promotions: BILLING_PROMOTIONS_EXAMPLE,
+            },
+        scopes: ["billing:write"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Redeem a promotion code",
+        surfaces: ["api", "mock"],
+    },
     BILLING_NOTICE_LIST_OPERATION,
     BILLING_NOTIFICATION_SETTINGS_OPERATION,
     BILLING_NOTIFICATION_SETTINGS_UPDATE_OPERATION,

package/dist/protocol.d.ts

@@ -54,6 +54,8 @@ export type ScheduleOrder = (typeof SCHEDULE_ORDERS)[number];
 export declare const scheduleListRequestSchema: import("zod").ZodObject<{
     cursor: import("zod").ZodOptional<import("zod").ZodString>;
     limit: import("zod").ZodDefault<import("zod").ZodNumber>;
+    external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+    tag: import("zod").ZodOptional<import("zod").ZodString>;
     dueBefore: import("zod").ZodOptional<import("zod").ZodString>;
     endpoint: import("zod").ZodOptional<import("zod").ZodString>;
     order: import("zod").ZodDefault<import("zod").ZodEnum<{

package/dist/protocol.js

@@ -1,4 +1,5 @@
 import { z } from "./zod.js";
+import { externalIdentifierSchema, scheduleTagSchema, } from "./host-correlation.js";
 import { PUBLIC_PAGE_SIZE } from "./configuration-bounds.js";
 import { endpointIdSchema, environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
 import { timestampSchema } from "./time.js";
@@ -55,6 +56,8 @@ export const SCHEDULE_ORDERS = ["created", "due"];
  * no instant to compare and inventing one either way would be a guess.
  */
 export const scheduleListRequestSchema = pageRequestSchema.extend({
+    external_identifier: externalIdentifierSchema.optional(),
+    tag: scheduleTagSchema.optional(),
     dueBefore: timestampSchema.optional(),
     endpoint: endpointIdSchema.optional(),
     order: z.enum(SCHEDULE_ORDERS).default("created"),

package/dist/scheduling-records.d.ts

@@ -117,6 +117,8 @@ export declare const portableScheduleRecordSchema: import("zod").ZodObject<{
         }>;
     }, import("zod/v4/core").$strict>;
     name: import("zod").ZodOptional<import("zod").ZodString>;
+    external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+    tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
     partitionKey: import("zod").ZodOptional<import("zod").ZodString>;
     nextDueAt: import("zod").ZodOptional<import("zod").ZodString>;
     recurrence: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
@@ -758,6 +760,8 @@ export declare const portableSchedulingRecordSetSchema: import("zod").ZodObject<
             }>;
         }, import("zod/v4/core").$strict>;
         name: import("zod").ZodOptional<import("zod").ZodString>;
+        external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+        tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
         partitionKey: import("zod").ZodOptional<import("zod").ZodString>;
         nextDueAt: import("zod").ZodOptional<import("zod").ZodString>;
         recurrence: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{

package/dist/scheduling.d.ts

@@ -371,6 +371,8 @@ export declare const projectOccurrenceListRequestSchema: import("zod").ZodObject
     cursor: import("zod").ZodOptional<import("zod").ZodString>;
     limit: import("zod").ZodDefault<import("zod").ZodNumber>;
     endpoint: import("zod").ZodOptional<import("zod").ZodString>;
+    external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+    tag: import("zod").ZodOptional<import("zod").ZodString>;
     from: import("zod").ZodOptional<import("zod").ZodString>;
     outcome: import("zod").ZodOptional<import("zod").ZodEnum<{
         succeeded: "succeeded";
@@ -786,6 +788,8 @@ export declare const scheduleSchema: import("zod").ZodObject<{
         }>;
     }, import("zod/v4/core").$strict>;
     name: import("zod").ZodOptional<import("zod").ZodString>;
+    external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+    tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
     partitionKey: import("zod").ZodOptional<import("zod").ZodString>;
     nextDueAt: import("zod").ZodOptional<import("zod").ZodString>;
     recurrence: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
@@ -886,6 +890,8 @@ export declare const schedulePageSchema: import("zod").ZodObject<{
             }>;
         }, import("zod/v4/core").$strict>;
         name: import("zod").ZodOptional<import("zod").ZodString>;
+        external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+        tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
         partitionKey: import("zod").ZodOptional<import("zod").ZodString>;
         nextDueAt: import("zod").ZodOptional<import("zod").ZodString>;
         recurrence: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
@@ -1622,6 +1628,8 @@ export declare const scheduleViewSchema: import("zod").ZodObject<{
             }>;
         }, import("zod/v4/core").$strict>;
         name: import("zod").ZodOptional<import("zod").ZodString>;
+        external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+        tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
         partitionKey: import("zod").ZodOptional<import("zod").ZodString>;
         nextDueAt: import("zod").ZodOptional<import("zod").ZodString>;
         recurrence: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
@@ -1748,6 +1756,8 @@ export declare const scheduleWrittenViewSchema: import("zod").ZodObject<{
             }>;
         }, import("zod/v4/core").$strict>;
         name: import("zod").ZodOptional<import("zod").ZodString>;
+        external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+        tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
         partitionKey: import("zod").ZodOptional<import("zod").ZodString>;
         nextDueAt: import("zod").ZodOptional<import("zod").ZodString>;
         recurrence: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
@@ -1861,6 +1871,8 @@ export declare const scheduleRequestSchema: import("zod").ZodObject<{
     }, import("zod/v4/core").$strict>>;
     partitionKey: import("zod").ZodOptional<import("zod").ZodString>;
     name: import("zod").ZodOptional<import("zod").ZodString>;
+    external_identifier: import("zod").ZodOptional<import("zod").ZodString>;
+    tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
     timeZone: import("zod").ZodOptional<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<string, string>>>;
 }, import("zod/v4/core").$strict>;
 export type ScheduleRequest = z.infer<typeof scheduleRequestSchema>;

package/dist/scheduling.js

@@ -1,6 +1,7 @@
 import { httpRequestSchema, publicHttpRequestSchema } from "./http-request.js";
 import { FIXED_INTERVAL_MIN_SECONDS, FIXED_INTERVAL_MAX_SECONDS, MAX_INLINE_PAYLOAD_BYTES, } from "./configuration-bounds.js";
 import { z } from "./zod.js";
+import { externalIdentifierSchema, scheduleTagSchema, scheduleTagsSchema, } from "./host-correlation.js";
 import { attemptIdSchema, deliveryIdSchema, endpointIdSchema, occurrenceIdSchema, scheduleIdSchema, } from "./identifiers.js";
 import { CALLBACK_ATTEMPT_DIAGNOSTICS } from "./delivery.js";
 import { callbackUrlSchema, signingSecretNoticeSchema } from "./endpoints.js";
@@ -380,6 +381,8 @@ export const occurrenceStateSchema = z.enum(OCCURRENCE_STATES);
 export const projectOccurrenceListRequestSchema = pageRequestSchema
     .extend({
     endpoint: endpointIdSchema.optional(),
+    external_identifier: externalIdentifierSchema.optional(),
+    tag: scheduleTagSchema.optional(),
     from: timestampSchema.optional(),
     outcome: occurrenceStateSchema.optional(),
     schedule: scheduleIdSchema.optional(),
@@ -395,6 +398,8 @@ const PROJECT_OCCURRENCE_LIST_PARAMETERS = [
     "cursor",
     "limit",
     "endpoint",
+    "external_identifier",
+    "tag",
     "from",
     "outcome",
     "schedule",
@@ -445,6 +450,10 @@ export function projectOccurrenceCursorBinding(request) {
         operation: "executions.list",
         parameters: {
             ...(request.endpoint === undefined ? {} : { endpoint: request.endpoint }),
+            ...(request.external_identifier === undefined
+                ? {}
+                : { external_identifier: request.external_identifier }),
+            ...(request.tag === undefined ? {} : { tag: request.tag }),
             ...(request.from === undefined ? {} : { from: request.from }),
             ...(request.outcome === undefined ? {} : { outcome: request.outcome }),
             ...(request.schedule === undefined ? {} : { schedule: request.schedule }),
@@ -917,6 +926,8 @@ export const scheduleSchema = z.object({
      * projection the migration has not reached, parses rather than fails.
      */
     name: scheduleNameSchema.optional(),
+    external_identifier: externalIdentifierSchema.optional(),
+    tags: scheduleTagsSchema.optional(),
     partitionKey: partitionKeySchema.optional(),
     /**
      * How this schedule recurs, in the vocabulary it will keep being read in.
@@ -1430,6 +1441,8 @@ export const scheduleRequestSchema = z
      * the person kept or changed. Names may collide.
      */
     name: scheduleNameSchema.optional(),
+    external_identifier: externalIdentifierSchema.optional(),
+    tags: scheduleTagsSchema.optional(),
     /**
      * The IANA timezone `cron` is read against. `UTC` when omitted.
      *

package/generated/v1/examples/billing.promotions.response.json

@@ -0,0 +1,26 @@
+{
+  "grants": [
+    {
+      "id": "grn_01hzy3v8k2m9q4r6t7w8x9y0za",
+      "source": "code",
+      "benefit": {
+        "kind": "credit",
+        "amount": {
+          "currency": "USD",
+          "microdollars": "10000000",
+          "scale": 6
+        }
+      },
+      "state": "active",
+      "startsAt": "2026-09-09T12:00:00.000Z",
+      "endsAt": "2026-12-08T12:00:00.000Z"
+    }
+  ],
+  "projectCapacity": {
+    "included": 1,
+    "paid": 0,
+    "complimentary": 0
+  },
+  "perks": [],
+  "restrictions": []
+}

package/generated/v1/examples/billing.redeem.request.json

@@ -0,0 +1,4 @@
+{
+  "code": "LAUNCH-2026",
+  "confirmed": true
+}

package/generated/v1/examples/billing.redeem.response.json

@@ -0,0 +1,43 @@
+{
+  "grant": {
+    "id": "grn_01hzy3v8k2m9q4r6t7w8x9y0za",
+    "source": "code",
+    "benefit": {
+      "kind": "credit",
+      "amount": {
+        "currency": "USD",
+        "microdollars": "10000000",
+        "scale": 6
+      }
+    },
+    "state": "active",
+    "startsAt": "2026-09-09T12:00:00.000Z",
+    "endsAt": "2026-12-08T12:00:00.000Z"
+  },
+  "promotions": {
+    "grants": [
+      {
+        "id": "grn_01hzy3v8k2m9q4r6t7w8x9y0za",
+        "source": "code",
+        "benefit": {
+          "kind": "credit",
+          "amount": {
+            "currency": "USD",
+            "microdollars": "10000000",
+            "scale": 6
+          }
+        },
+        "state": "active",
+        "startsAt": "2026-09-09T12:00:00.000Z",
+        "endsAt": "2026-12-08T12:00:00.000Z"
+      }
+    ],
+    "projectCapacity": {
+      "included": 1,
+      "paid": 0,
+      "complimentary": 0
+    },
+    "perks": [],
+    "restrictions": []
+  }
+}

package/generated/v1/manifest.json

@@ -51,11 +51,14 @@
     "examples/billing.paymentmethodsetup.response.json",
     "examples/billing.portal.response.json",
     "examples/billing.projects.response.json",
+    "examples/billing.promotions.response.json",
     "examples/billing.purchase.request.json",
     "examples/billing.purchase.response.json",
     "examples/billing.quote.request.json",
     "examples/billing.quote.response.json",
     "examples/billing.reconcile.response.json",
+    "examples/billing.redeem.request.json",
+    "examples/billing.redeem.response.json",
     "examples/billing.refundrequest.request.json",
     "examples/billing.refundrequest.response.json",
     "examples/billing.refundresolution.request.json",
@@ -211,6 +214,7 @@
     "schemas/billing.paymentmethodsetup.response.json",
     "schemas/billing.portal.response.json",
     "schemas/billing.projects.response.json",
+    "schemas/billing.promotions.response.json",
     "schemas/billing.purchase.request-headers.json",
     "schemas/billing.purchase.request.json",
     "schemas/billing.purchase.response-headers.json",
@@ -218,6 +222,10 @@
     "schemas/billing.quote.request.json",
     "schemas/billing.quote.response.json",
     "schemas/billing.reconcile.response.json",
+    "schemas/billing.redeem.request-headers.json",
+    "schemas/billing.redeem.request.json",
+    "schemas/billing.redeem.response-headers.json",
+    "schemas/billing.redeem.response.json",
     "schemas/billing.refundrequest.request-headers.json",
     "schemas/billing.refundrequest.request.json",
     "schemas/billing.refundrequest.response-headers.json",
@@ -398,9 +406,11 @@
     "snippets/billing.paymentmethodsetup.json",
     "snippets/billing.portal.json",
     "snippets/billing.projects.json",
+    "snippets/billing.promotions.json",
     "snippets/billing.purchase.json",
     "snippets/billing.quote.json",
     "snippets/billing.reconcile.json",
+    "snippets/billing.redeem.json",
     "snippets/billing.refundrequest.json",
     "snippets/billing.refundresolution.json",
     "snippets/billing.summary.json",
@@ -1830,6 +1840,52 @@
       "sessionAuthority": "headers",
       "surfaces": ["api", "mock"]
     },
+    {
+      "id": "billing.promotions",
+      "method": "GET",
+      "mutates": false,
+      "path": "/v1/billing/promotions",
+      "principals": ["api-credential", "oauth", "session"],
+      "problems": [
+        "authentication_required",
+        "capability_not_configured",
+        "credential_expired",
+        "credential_revoked",
+        "project_archived",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable",
+        "test_to_live_escalation"
+      ],
+      "scopes": ["usage:read"],
+      "sessionAuthority": "headers",
+      "surfaces": ["api", "mock"]
+    },
+    {
+      "id": "billing.redeem",
+      "method": "POST",
+      "mutates": true,
+      "path": "/v1/billing/promotions/redeem",
+      "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",
+        "scope_missing",
+        "service_unavailable",
+        "state_conflict",
+        "test_to_live_escalation"
+      ],
+      "scopes": ["billing:write"],
+      "sessionAuthority": "headers",
+      "surfaces": ["api", "mock"]
+    },
     {
       "id": "billing.notices",
       "method": "GET",