@stackshift-cloud/sdk 1.3.1 → 1.4.1

package/dist/mail-webhook-types.d.ts

@@ -1,6 +1,14 @@
 import type { MailMode } from './mail-simulation.js';
 import type { JsonValue } from './types.js';
-export type MailEventType = 'mail.message.opened' | 'mail.message.clicked' | 'mail.message.accepted' | 'mail.message.queued' | 'mail.message.sending' | 'mail.message.mta_accepted' | 'mail.delivery.delayed' | 'mail.delivery.delivered' | 'mail.message.failed' | 'mail.message.bounced' | 'mail.message.suppressed' | 'mail.message.complained' | 'mail.suppression.created' | 'mail.suppression.deleted' | 'mail.otp.created' | 'mail.otp.sent' | 'mail.otp.verified' | 'mail.otp.failed_attempt' | 'mail.otp.failed' | 'mail.otp.expired' | 'mail.otp.canceled' | 'mail.template.created' | 'mail.template.updated' | 'mail.template.deleted' | 'mail.template.version.created' | 'mail.template.test_queued' | 'mail.domain.created' | 'mail.domain.verified' | 'mail.domain.failed' | 'mail.domain.deleted' | 'mail.webhook.created' | 'mail.webhook.updated' | 'mail.webhook.disabled' | 'mail.webhook.delivery.succeeded' | 'mail.webhook.delivery.failed' | 'mail.audience.created' | 'mail.audience.members.imported' | 'mail.campaign.created' | 'mail.campaign.queued';
+export type MailEventType = 'mail.message.opened' | 'mail.message.clicked' | 'mail.message.accepted' | 'mail.message.queued' | 'mail.message.sending' | 'mail.message.mta_accepted' | 'mail.delivery.delayed' | 'mail.delivery.delivered' | 'mail.message.failed' | 'mail.message.bounced' | 'mail.message.suppressed' | 'mail.message.complained' | 'mail.suppression.created' | 'mail.suppression.deleted' | 'mail.otp.created' | 'mail.otp.sent' | 'mail.otp.verified' | 'mail.otp.failed_attempt' | 'mail.otp.failed' | 'mail.otp.expired' | 'mail.otp.canceled' | 'mail.template.created' | 'mail.template.updated' | 'mail.template.deleted' | 'mail.template.version.created' | 'mail.template.test_queued' | 'mail.domain.created' | 'mail.domain.verified' | 'mail.domain.failed' | 'mail.domain.deleted' | 'mail.webhook.created' | 'mail.webhook.updated' | 'mail.webhook.disabled' | 'mail.webhook.delivery.succeeded' | 'mail.webhook.delivery.failed' | 'mail.audience.created' | 'mail.audience.members.imported' | 'mail.campaign.created' | 'mail.campaign.queued' | 'mail.campaign.stopped' | 'partner.domain.registered' | 'partner.domain.failed' | 'partner.domain.dns_verified' | 'partner.brand.ready' | 'partner.warmup.progress' | 'partner.brand.warning' | 'partner.brand.paused' | 'partner.brand.resumed' | 'partner.brand.bounced' | 'partner.brand.complained' | 'partner.domain.renewal_due' | 'partner.domain.renewed' | 'partner.domain.renewal_failed';
+export interface MailCampaignStoppedEvent {
+    campaignId: string;
+    brandId: string;
+    reason: 'sender_paused';
+    pauseReason: 'complaint_rate' | 'bounce_rate' | 'partner_suspended' | string;
+    pausedSince: string;
+    message: string;
+}
 export interface MailEvent {
     mode?: MailMode;
     id: string;
@@ -43,6 +51,20 @@ export interface MailWebhook {
     lastFailureAt?: string | null;
     createdAt: string;
 }
+export interface MailWebhookWaitingHighlight {
+    type: string;
+    shop: string;
+}
+export interface MailWebhookWaitingSummary {
+    count: number;
+    capped: boolean;
+    oldestAt: string;
+    merchantUpdates: number;
+    highlights: MailWebhookWaitingHighlight[];
+}
+export interface MailWebhookDetail extends MailWebhook {
+    waitingSummary: MailWebhookWaitingSummary | null;
+}
 export interface MailWebhookCreateInput {
     url: string;
     description?: string;
@@ -80,6 +102,23 @@ export interface MailWebhookDelivery {
     createdAt: string;
     completedAt?: string | null;
 }
+export interface MailWebhookDeliveryMerchant {
+    partnerDomainId: string;
+    merchantRef: string;
+    shop: string;
+}
+export interface MailWebhookDeliveryListItem extends MailWebhookDelivery {
+    durationMs: number | null;
+    merchant: MailWebhookDeliveryMerchant | null;
+}
+export interface MailWebhookDiagnosis {
+    checkedAt: string;
+    repliesRead: number;
+    summary: string;
+}
+export interface MailWebhookDiagnosisResult {
+    diagnosis: MailWebhookDiagnosis | null;
+}
 export interface MailWebhookDeliveryAttempt {
     id: string;
     attemptNumber: number;

package/dist/mail.d.ts

@@ -19,6 +19,8 @@ import { MailAudiencesClient, MailCampaignsClient } from './mail-campaigns.js';
 export { MailAudiencesClient, MailCampaignsClient } from './mail-campaigns.js';
 import { MailExportsClient } from './mail-exports.js';
 export { MailExportsClient } from './mail-exports.js';
+import { MailboxAliasesClient, MailboxDomainsClient, MailboxGroupsClient, MailboxImportsClient, MailboxRoutesClient, MailboxesClient } from './mail-mailboxes.js';
+export { MailboxAliasesClient, MailboxDomainsClient, MailboxGroupsClient, MailboxImportsClient, MailboxRoutesClient, MailboxesClient } from './mail-mailboxes.js';
 import type { MailTemplateDiagnosticInput, MailTemplateDiagnosticResult } from './mail-diagnostics.js';
 export declare class MailClient {
     private readonly client;
@@ -41,6 +43,12 @@ export declare class MailClient {
     readonly audiences: MailAudiencesClient;
     readonly campaigns: MailCampaignsClient;
     readonly exports: MailExportsClient;
+    readonly mailboxDomains: MailboxDomainsClient;
+    readonly mailboxes: MailboxesClient;
+    readonly aliases: MailboxAliasesClient;
+    readonly groups: MailboxGroupsClient;
+    readonly routes: MailboxRoutesClient;
+    readonly mailboxImports: MailboxImportsClient;
     readonly limits: MailLimitsClient;
     readonly reputation: MailReputationClient;
     readonly scheduled: MailScheduledClient;

package/dist/mail.js

@@ -13,6 +13,8 @@ import { MailAudiencesClient, MailCampaignsClient } from './mail-campaigns.js';
 export { MailAudiencesClient, MailCampaignsClient } from './mail-campaigns.js';
 import { MailExportsClient } from './mail-exports.js';
 export { MailExportsClient } from './mail-exports.js';
+import { MailboxAliasesClient, MailboxDomainsClient, MailboxGroupsClient, MailboxImportsClient, MailboxRoutesClient, MailboxesClient } from './mail-mailboxes.js';
+export { MailboxAliasesClient, MailboxDomainsClient, MailboxGroupsClient, MailboxImportsClient, MailboxRoutesClient, MailboxesClient } from './mail-mailboxes.js';
 export class MailClient {
     client;
     automations;
@@ -34,6 +36,12 @@ export class MailClient {
     audiences;
     campaigns;
     exports;
+    mailboxDomains;
+    mailboxes;
+    aliases;
+    groups;
+    routes;
+    mailboxImports;
     limits;
     reputation;
     scheduled;
@@ -61,6 +69,12 @@ export class MailClient {
         this.audiences = new MailAudiencesClient(client);
         this.campaigns = new MailCampaignsClient(client);
         this.exports = new MailExportsClient(client);
+        this.mailboxDomains = new MailboxDomainsClient(client);
+        this.mailboxes = new MailboxesClient(client);
+        this.aliases = new MailboxAliasesClient(client);
+        this.groups = new MailboxGroupsClient(client);
+        this.routes = new MailboxRoutesClient(client);
+        this.mailboxImports = new MailboxImportsClient(client);
         this.limits = new MailLimitsClient(client);
         this.reputation = new MailReputationClient(client);
         this.scheduled = new MailScheduledClient(client);
@@ -248,6 +262,7 @@ export class MailSuppressionsClient {
         const query = new URLSearchParams();
         append(query, 'email', options.email);
         append(query, 'reason', options.reason);
+        append(query, 'brandId', options.brandId);
         append(query, 'limit', options.limit);
         append(query, 'cursor', options.cursor);
         const suffix = query.toString();

package/dist/partner.d.ts

@@ -0,0 +1,369 @@
+import type { StackShift } from './client.js';
+import type { MailBrand } from './mail-brands.js';
+import type { JsonValue } from './types.js';
+export type PartnerDomainState = 'registering' | 'mail_setup' | 'verifying' | 'replies' | 'brand_setup' | 'ready' | 'failed';
+export type PartnerRepliesMode = 'forward' | 'mailbox';
+export interface PartnerAccount {
+    userId: string;
+    name: string;
+    status: 'active' | 'suspended' | string;
+    complaintPauseRate: number;
+    bouncePauseRate: number;
+    dedicatedPoolName: string | null;
+    dailyPurchaseLimit: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PartnerWalletBalance {
+    currency: string;
+    balance_minor: number;
+    held_minor: number;
+    disputed_minor: number;
+    available_minor: number;
+}
+export interface PartnerLimits {
+    maxComplaintPauseRate: number;
+    maxBouncePauseRate: number;
+    minimumRecipients: number;
+    windowDays: number;
+    shortWindowHours: number;
+    dailyPurchaseLimit: number;
+    warningFraction: number;
+    merchantSharePercent: number;
+    merchantCount: number;
+    dailySendingLimit: number;
+    hourlySendingLimit: number;
+}
+export interface PartnerOverview {
+    account: PartnerAccount;
+    wallet: PartnerWalletBalance[];
+    webhookEvents: string[];
+    limits: PartnerLimits;
+}
+export interface PartnerSettingsInput {
+    complaintPauseRate: number;
+    bouncePauseRate: number;
+}
+export interface PartnerRegistrant {
+    first_name: string;
+    last_name: string;
+    organization?: string;
+    email: string;
+    phone: string;
+    address: string;
+    city: string;
+    state: string;
+    postal_code: string;
+    country: string;
+}
+export interface PartnerBrandInput {
+    name: string;
+    fromLocalPart?: string;
+    postalAddress: string;
+    website?: string;
+    supportEmail?: string;
+}
+export interface PartnerRepliesInput {
+    mode: PartnerRepliesMode;
+    forwardTo?: string;
+    mailboxOwnerEmail?: string;
+    mailboxPlan?: string;
+}
+export interface PartnerDomainPurchaseInput {
+    domain: string;
+    years: number;
+    currency?: 'NGN' | 'USD';
+    merchantRef: string;
+    registrant: PartnerRegistrant;
+    brand: PartnerBrandInput;
+    replies: PartnerRepliesInput;
+}
+export interface PartnerPurchaseOptions {
+    idempotencyKey: string;
+}
+export type PartnerFailureCode = 'nameservers_changed' | 'dns_not_visible' | 'wallet_short' | 'registry_taken' | 'registration_rejected' | 'registration_timed_out' | 'purchase_interrupted' | 'mailbox_unavailable' | 'mail_setup_rejected' | 'dns_provider_error' | 'registration_mismatch' | 'sending_domains_missing' | 'internal_retrying';
+export interface PartnerFailureFact {
+    label: string;
+    value: string;
+    tone: 'bad' | 'ok' | 'neutral';
+    at: string | null;
+}
+export type PartnerFailureFix = {
+    label: string;
+    action: 'restore_nameservers';
+} | {
+    label: string;
+    href: string;
+};
+export interface PartnerFailure {
+    code: PartnerFailureCode;
+    title: string;
+    headline: string;
+    explanation: string;
+    since: string | null;
+    facts: PartnerFailureFact[];
+    data: Record<string, JsonValue>;
+    fix: PartnerFailureFix | null;
+    canRetry: boolean;
+}
+export interface PartnerDiagnosis {
+    checkedAt: string;
+    summary: string;
+}
+export interface PartnerPause {
+    reason: 'complaint_rate' | 'bounce_rate';
+    rate: number;
+    limit: number;
+    window: 'last_7_days' | 'last_24_hours';
+    campaignId: string | null;
+    campaignName: string | null;
+    listId: string | null;
+    listName: string | null;
+    listImportedAt: string | null;
+    listShare: number | null;
+    recoversAt: string | null;
+}
+export interface PartnerWaitingFor {
+    kind: 'wallet';
+    currency: string;
+    requiredMinor: number;
+    availableMinor: number;
+}
+export interface PartnerRefund {
+    amountMinor: number;
+    currency: string;
+    at: string;
+}
+export interface PartnerMerchantDomain {
+    id: string;
+    partnerUserId: string;
+    merchantRef: string;
+    domain: string;
+    years: number;
+    domainOrderId: string | null;
+    registeredDomainId: string | null;
+    mailDomainId: string | null;
+    brandId: string | null;
+    mailboxDomainId: string | null;
+    mailboxId: string | null;
+    brand: PartnerBrandInput;
+    registrant: PartnerRegistrant;
+    replies: PartnerRepliesInput;
+    state: PartnerDomainState;
+    failedState: PartnerDomainState | null;
+    lastError: string;
+    attempts: number;
+    nextAttemptAt: string;
+    lastAttemptAt: string | null;
+    waitingFor: PartnerWaitingFor | null;
+    warmupDay: number;
+    healthWarnedAt: string | null;
+    transferredOutAt: string | null;
+    amountMinor: number;
+    currency: string;
+    walletReference: string;
+    createdAt: string;
+    updatedAt: string;
+    expiryDate: string | null;
+    brandPausedAt: string | null;
+    brandPauseReason: 'complaint_rate' | 'bounce_rate' | '';
+    pause: PartnerPause | null;
+    failure: PartnerFailure | null;
+    diagnosis: PartnerDiagnosis | null;
+}
+export interface PartnerDomainListOptions {
+    merchantRef?: string;
+    q?: string;
+    attention?: boolean;
+    limit?: number;
+    offset?: number;
+}
+export interface PartnerWarmupSummary {
+    status: string;
+    day: number;
+    totalDays: number;
+    marketingUnlocked: boolean;
+    marketingOpensInDays: number;
+}
+export interface PartnerDomainListItem extends PartnerMerchantDomain {
+    health: PartnerBrandHealth | null;
+    transactionalHealth: PartnerBrandHealth | null;
+    refunded: boolean;
+    sentByDay: number[];
+    warmup: PartnerWarmupSummary | null;
+}
+export interface PartnerDomainList {
+    domains: PartnerDomainListItem[];
+    total: number;
+    attentionTotal: number;
+}
+export interface PartnerSenders {
+    marketing: string;
+    transactional: string;
+    replyTo: string;
+}
+export interface PartnerHealthWindow {
+    attempted: number;
+    accepted: number;
+    bounced: number;
+    complained: number;
+    bounceRate: number;
+    complaintRate: number;
+}
+export interface PartnerBrandHealth extends PartnerHealthWindow {
+    last24h: PartnerHealthWindow;
+}
+export interface PartnerWarmup {
+    status: string;
+    day: number;
+    totalDays: number;
+    dailyLimit: number;
+    marketingDailyLimit: number;
+    marketingUnlocked: boolean;
+    cleanTransactionalDays: number;
+    requiredCleanDays: number;
+    firstCampaignCap: number;
+    paused: boolean;
+    marketingSentToday: number;
+    marketingOpensInDays: number;
+}
+export type PartnerRecordPurpose = 'dkim' | 'spf' | 'return_path' | 'dmarc' | 'reply_mx' | 'reply_ownership' | 'mta_sts' | 'mta_sts_policy' | 'tls_reporting';
+export interface PartnerRecord {
+    domain: string;
+    type: string;
+    name: string;
+    value: string;
+    priority: number | null;
+    verified: boolean;
+    purpose: PartnerRecordPurpose;
+}
+export interface PartnerDomainView extends PartnerMerchantDomain {
+    senders: PartnerSenders;
+    brandStatus: MailBrand | null;
+    health: PartnerBrandHealth | null;
+    transactionalHealth: PartnerBrandHealth | null;
+    warmup: PartnerWarmup | null;
+    replies: PartnerRepliesInput & {
+        mailboxOwnerName: string | null;
+    };
+    records: PartnerRecord[];
+    refunded: boolean;
+    refund: PartnerRefund | null;
+    webhookDeliveredAt: string | null;
+}
+export interface PartnerTransferOut {
+    domain: string;
+    authCode: string;
+}
+export interface PartnerUsageOptions {
+    from?: string;
+    to?: string;
+}
+export interface PartnerBrandUsage {
+    partnerDomainId: string;
+    merchantRef: string;
+    domain: string;
+    brandId: string | null;
+    brandName: string;
+    marketingRecipients: number;
+    transactionalRecipients: number;
+    domainChargesMinor: number;
+    refundedMinor: number;
+    currency: string;
+}
+export interface PartnerUsage {
+    from: string;
+    to: string;
+    brands: PartnerBrandUsage[];
+}
+export interface PartnerComplaintSummary {
+    complained: number;
+    suppressed: number;
+}
+export interface PartnerComplaintSource {
+    audienceId: string;
+    audienceName: string;
+    importedAt: string | null;
+    contacts: number;
+    neverOpened: number;
+    complained: number;
+}
+export interface PartnerBulkSuppressionInput {
+    audienceId: string;
+    reason: 'never_opened';
+}
+export interface PartnerBulkSuppression {
+    id: string;
+    audienceId: string;
+    reason: 'never_opened';
+    suppressed: number;
+}
+export type PartnerRequestKind = 'purchase_limit' | 'dedicated_addresses';
+export interface PartnerRequestInput {
+    kind: PartnerRequestKind;
+    message?: string;
+}
+export interface PartnerRequest {
+    id: string;
+    kind: PartnerRequestKind;
+    message: string;
+    status: 'open' | 'done' | 'declined';
+    resolvedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PartnerEventBase {
+    partnerDomainId: string;
+    merchantRef: string;
+    domain: string;
+    state: PartnerDomainState;
+    brandId?: string;
+}
+export interface PartnerBrandHealthEvent extends PartnerEventBase {
+    bounceRate: number;
+    complaintRate: number;
+    recipients: number;
+    last24h: PartnerHealthWindow;
+    bounceLimit: number;
+    complaintLimit: number;
+    reason?: 'complaint_rate' | 'bounce_rate';
+}
+export interface PartnerDomainRenewedEvent extends PartnerEventBase {
+    expiryDate: string;
+    previousExpiryDate: string;
+}
+export interface PartnerDomainRenewalDueEvent extends PartnerEventBase {
+    expiryDate: string;
+    autoRenew: boolean;
+}
+export interface PartnerDomainRenewalFailedEvent extends PartnerEventBase {
+    expiryDate: string;
+    reason: string;
+    amountMinor: number;
+    currency: string;
+}
+export declare class PartnerClient {
+    private readonly client;
+    constructor(client: StackShift);
+    overview(): Promise<PartnerOverview>;
+    updateSettings(input: PartnerSettingsInput): Promise<PartnerAccount>;
+    purchaseDomain(input: PartnerDomainPurchaseInput, { idempotencyKey }: PartnerPurchaseOptions): Promise<PartnerMerchantDomain>;
+    listDomains(options?: PartnerDomainListOptions): Promise<PartnerDomainList>;
+    getDomain(id: string): Promise<PartnerDomainView>;
+    retryDomain(id: string): Promise<PartnerMerchantDomain>;
+    transferOut(id: string): Promise<PartnerTransferOut>;
+    getDiagnosis(id: string): Promise<PartnerDiagnosis>;
+    restoreDns(id: string): Promise<PartnerMerchantDomain>;
+    resumeBrand(brandId: string): Promise<MailBrand>;
+    getComplaints(brandId: string): Promise<PartnerComplaintSummary>;
+    listComplaintSources(brandId: string): Promise<PartnerComplaintSource[]>;
+    suppressNeverOpened(brandId: string, input: PartnerBulkSuppressionInput): Promise<PartnerBulkSuppression>;
+    undoSuppression(brandId: string, bulkId: string): Promise<{
+        restored: number;
+    }>;
+    usage(options?: PartnerUsageOptions): Promise<PartnerUsage>;
+    listRequests(): Promise<{
+        requests: PartnerRequest[];
+    }>;
+    createRequest(input: PartnerRequestInput): Promise<PartnerRequest>;
+}

package/dist/partner.js

@@ -0,0 +1,70 @@
+export class PartnerClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    overview() {
+        return this.client.request('/partner');
+    }
+    updateSettings(input) {
+        return this.client.request('/partner/settings', { method: 'PUT', body: input });
+    }
+    purchaseDomain(input, { idempotencyKey }) {
+        return this.client.request('/partner/domains', {
+            method: 'POST',
+            headers: { 'Idempotency-Key': idempotencyKey },
+            body: input,
+        });
+    }
+    listDomains(options = {}) {
+        return this.client.request(`/partner/domains${queryString(options)}`);
+    }
+    getDomain(id) {
+        return this.client.request(`/partner/domains/${encodeURIComponent(id)}`);
+    }
+    retryDomain(id) {
+        return this.client.request(`/partner/domains/${encodeURIComponent(id)}/retry`, { method: 'POST' });
+    }
+    transferOut(id) {
+        return this.client.request(`/partner/domains/${encodeURIComponent(id)}/transfer-out`, { method: 'POST' });
+    }
+    getDiagnosis(id) {
+        return this.client.request(`/partner/domains/${encodeURIComponent(id)}/diagnosis`);
+    }
+    restoreDns(id) {
+        return this.client.request(`/partner/domains/${encodeURIComponent(id)}/restore-dns`, { method: 'POST' });
+    }
+    resumeBrand(brandId) {
+        return this.client.request(`/partner/brands/${encodeURIComponent(brandId)}/resume`, { method: 'POST' });
+    }
+    getComplaints(brandId) {
+        return this.client.request(`/partner/brands/${encodeURIComponent(brandId)}/complaints`);
+    }
+    listComplaintSources(brandId) {
+        return this.client.request(`/partner/brands/${encodeURIComponent(brandId)}/complaints/sources`);
+    }
+    suppressNeverOpened(brandId, input) {
+        return this.client.request(`/partner/brands/${encodeURIComponent(brandId)}/suppressions/bulk`, { method: 'POST', body: input });
+    }
+    undoSuppression(brandId, bulkId) {
+        return this.client.request(`/partner/brands/${encodeURIComponent(brandId)}/suppressions/bulk/${encodeURIComponent(bulkId)}/undo`, { method: 'POST' });
+    }
+    usage(options = {}) {
+        return this.client.request(`/partner/usage${queryString(options)}`);
+    }
+    listRequests() {
+        return this.client.request('/partner/requests');
+    }
+    createRequest(input) {
+        return this.client.request('/partner/requests', { method: 'POST', body: input });
+    }
+}
+function queryString(options) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined)
+            query.set(key, String(value));
+    }
+    const suffix = query.toString();
+    return suffix ? `?${suffix}` : '';
+}

package/dist/support-action-manifest.d.ts

@@ -0,0 +1,3 @@
+import type { SupportActionDescriptor } from './support-action-types.js';
+/** Validate action declarations locally; server registration and destination checks remain authoritative. */
+export declare function validateSupportActionCatalog(version: string, actions: SupportActionDescriptor[]): void;

package/dist/support-action-manifest.js

@@ -0,0 +1,40 @@
+import { actionCheck } from './support-actions.js';
+const reserved = new Set(['customer', 'customer_id', 'external_customer_id', 'external_id', 'contact_id', 'workspace_id', 'environment_id', 'inbox_id', 'conversation_id', 'installation_id', 'tenant_id', 'user_id', 'organization_id', 'authorization', 'scope', 'identity', 'credentials', 'secret', 'token']);
+function endpoint(value) {
+    if (!value || value.length > 2048)
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && !!url.hostname && !url.username && !url.password && !url.search && !url.hash && !value.includes('?') && !value.includes('#');
+    }
+    catch {
+        return false;
+    }
+}
+function fields(schema, input) {
+    actionCheck(schema && typeof schema === 'object' && !Array.isArray(schema) && Object.keys(schema).length <= 32, 'invalid_catalog');
+    for (const [name, field] of Object.entries(schema)) {
+        actionCheck(/^[a-z][a-z0-9_]{0,63}$/.test(name) && (!input || (!reserved.has(name) && !/^(customer_|tenant_|auth_)/.test(name))), 'invalid_catalog');
+        actionCheck(field && typeof field.required === 'boolean' && Object.keys(field).every(k => ['type', 'required', 'max_length', 'minimum', 'maximum', 'enum'].includes(k)), 'invalid_catalog');
+        if (field.type === 'string')
+            actionCheck(Number.isInteger(field.max_length) && field.max_length >= 1 && field.max_length <= 16000 && field.minimum === undefined && field.maximum === undefined && (!field.enum || (Array.isArray(field.enum) && field.enum.length <= 64 && new Set(field.enum).size === field.enum.length && field.enum.every(v => typeof v === 'string' && [...v].length <= field.max_length))), 'invalid_catalog');
+        else if (field.type === 'number' || field.type === 'integer')
+            actionCheck(!field.max_length && !field.enum?.length && [field.minimum, field.maximum].every(n => n === undefined || (Number.isFinite(n) && (field.type !== 'integer' || Number.isSafeInteger(n)))) && (field.minimum === undefined || field.maximum === undefined || field.minimum <= field.maximum), 'invalid_catalog');
+        else
+            actionCheck(field.type === 'boolean' && !field.max_length && !field.enum?.length && field.minimum === undefined && field.maximum === undefined, 'invalid_catalog');
+    }
+}
+/** Validate action declarations locally; server registration and destination checks remain authoritative. */
+export function validateSupportActionCatalog(version, actions) {
+    actionCheck(typeof version === 'string' && version.length <= 32 && /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(version) && Array.isArray(actions) && actions.length >= 1 && actions.length <= 32, 'invalid_catalog');
+    const names = new Set();
+    for (const action of actions) {
+        actionCheck(/^[a-z][a-z0-9_.]{0,79}$/.test(action.name) && !names.has(action.name) && action.version === version && action.identity_required === true && ['read', 'bounded_write', 'customer_change', 'financial', 'security'].includes(action.risk) && typeof action.idempotency_supported === 'boolean' && typeof action.safe_retry === 'boolean' && Number.isInteger(action.timeout_seconds) && action.timeout_seconds >= 1 && action.timeout_seconds <= 30 && endpoint(action.endpoint), 'invalid_catalog');
+        actionCheck((action.risk === 'read' || (action.idempotency_supported && endpoint(action.reconciliation_endpoint) && !!action.verification_operation)) && (!action.safe_retry || action.idempotency_supported) && (!action.reconciliation_endpoint || endpoint(action.reconciliation_endpoint)), 'invalid_catalog');
+        fields(action.input, true);
+        fields(action.output, false);
+        names.add(action.name);
+    }
+    for (const action of actions)
+        actionCheck(!action.verification_operation || actions.some(a => a.name === action.verification_operation && a.risk === 'read'), 'invalid_catalog');
+}

package/dist/support-action-receiver.d.ts

@@ -0,0 +1,20 @@
+import type { SupportActionReceipt, SupportActionRequest, SupportActionVerification } from './support-action-types.js';
+export interface SupportActionClaim {
+    state: 'acquired' | 'completed' | 'running' | 'unknown' | 'conflict';
+    fence?: string;
+    response?: Uint8Array;
+}
+export interface SupportActionDurableStore {
+    claim(namespace: 'delivery' | 'execution', key: string, digest: string): Promise<SupportActionClaim>;
+    complete(namespace: 'delivery' | 'execution', key: string, fence: string, response: Uint8Array, unknown?: boolean): Promise<void>;
+}
+export type SupportActionHandler = (request: SupportActionRequest) => Promise<Pick<SupportActionReceipt, 'state' | 'result' | 'error_code'>>;
+export declare function receiveSupportAction(raw: Uint8Array, headers: Record<string, string>, options: {
+    verification: SupportActionVerification;
+    store: SupportActionDurableStore;
+    execute: SupportActionHandler;
+    reconcile: SupportActionHandler;
+}): Promise<{
+    body: Uint8Array<ArrayBufferLike>;
+    headers: Record<string, string>;
+}>;

package/dist/support-action-receiver.js

@@ -0,0 +1,37 @@
+import { ACTION_RECEIPT_CONTEXT, actionCheck, actionHeaders, encodeSupportActionReceipt, signSupportAction, validateSupportActionFields, verifySupportAction } from './support-actions.js';
+export async function receiveSupportAction(raw, headers, options) {
+    const verification = { ...options.verification, now: options.verification.now ?? Math.floor(Date.now() / 1000) };
+    const request = await verifySupportAction(raw, headers, verification);
+    const delivery = actionHeaders(headers)['x-stackshift-delivery-id'];
+    const digest = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', new Uint8Array(raw))), b => b.toString(16).padStart(2, '0')).join('');
+    const deliveryKey = `${request.installation_id}:${delivery}`;
+    const deliveryClaim = await options.store.claim('delivery', deliveryKey, digest);
+    actionCheck(deliveryClaim.state === 'acquired' && deliveryClaim.fence, 'delivery_replay');
+    const key = [request.installation_id, request.action.name, request.action.version, request.request_id, request.mode].join(':');
+    const claim = await options.store.claim('execution', key, digest);
+    actionCheck(claim.state !== 'conflict', 'idempotency_conflict');
+    let response;
+    if ((claim.state === 'completed' || claim.state === 'unknown') && claim.response)
+        response = claim.response;
+    else if (claim.state === 'running' || claim.state === 'unknown')
+        response = encodeSupportActionReceipt(request.request_id, claim.state === 'unknown' ? 'unknown' : 'accepted', {}, claim.state === 'unknown' ? 'execution_unknown' : 'execution_in_progress');
+    else {
+        actionCheck(claim.state === 'acquired' && claim.fence, 'invalid_store_claim');
+        let state = 'unknown';
+        try {
+            const result = await (request.mode === 'reconcile' ? options.reconcile : options.execute)(request);
+            state = result.state;
+            const action = verification.actions.find(a => a.name === request.action.name && a.version === request.action.version);
+            if (state === 'succeeded')
+                validateSupportActionFields(result.result, action.output);
+            response = encodeSupportActionReceipt(request.request_id, state, result.result, result.error_code);
+        }
+        catch {
+            state = 'unknown';
+            response = encodeSupportActionReceipt(request.request_id, state, {}, 'handler_outcome_unknown');
+        }
+        await options.store.complete('execution', key, claim.fence, response, state === 'unknown');
+    }
+    await options.store.complete('delivery', deliveryKey, deliveryClaim.fence, response);
+    return { body: response, headers: await signSupportAction(response, ACTION_RECEIPT_CONTEXT, verification.keyID, verification.secret, verification.now, delivery) };
+}