@phpsandbox/sdk 0.5.0 → 0.6.0-canary.0

package/dist/customers.d.ts

@@ -1,5 +1,32 @@
 import { z } from 'zod';
 import type { Client } from './index.js';
+declare const customerConfigurationSchema: z.ZodObject<{
+    funnel: z.ZodNullable<z.ZodObject<{
+        title: z.ZodString;
+        stages: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            measure: z.ZodLiteral<"event">;
+            event: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            measure: z.ZodLiteral<"first_payment">;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            measure: z.ZodLiteral<"event_after_payment">;
+            event: z.ZodString;
+        }, z.core.$strip>], "measure">>;
+    }, z.core.$strip>>;
+    followUp: z.ZodNullable<z.ZodObject<{
+        label: z.ZodString;
+        triggerEvent: z.ZodString;
+        prerequisiteEvent: z.ZodNullable<z.ZodString>;
+        stopOnPayment: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CustomerConfiguration = z.infer<typeof customerConfigurationSchema>;
 export declare const customerModeSchema: z.ZodEnum<{
     test: "test";
     live: "live";
@@ -12,6 +39,21 @@ export declare const customerSchema: z.ZodObject<{
     name: z.ZodNullable<z.ZodString>;
     source: z.ZodNullable<z.ZodString>;
     marketingSubscribed: z.ZodBoolean;
+    communicationBasis: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        legacy_account: "legacy_account";
+        explicit_opt_in: "explicit_opt_in";
+        unsubscribed: "unsubscribed";
+    }>>;
+    legacyPolicy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    joinedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    importedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    lastActiveAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    billingStatus: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        paid: "paid";
+        free: "free";
+    }>>;
     suppressionReason: z.ZodNullable<z.ZodString>;
     activatedAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodNullable<z.ZodString>;
@@ -29,6 +71,33 @@ declare const spaceSchema: z.ZodObject<{
     replyTo: z.ZodNullable<z.ZodString>;
     senderVerified: z.ZodBoolean;
     domainRecords: z.ZodNullable<z.ZodString>;
+    configuration: z.ZodOptional<z.ZodObject<{
+        funnel: z.ZodNullable<z.ZodObject<{
+            title: z.ZodString;
+            stages: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                measure: z.ZodLiteral<"event">;
+                event: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                measure: z.ZodLiteral<"first_payment">;
+            }, z.core.$strip>, z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                measure: z.ZodLiteral<"event_after_payment">;
+                event: z.ZodString;
+            }, z.core.$strip>], "measure">>;
+        }, z.core.$strip>>;
+        followUp: z.ZodNullable<z.ZodObject<{
+            label: z.ZodString;
+            triggerEvent: z.ZodString;
+            prerequisiteEvent: z.ZodNullable<z.ZodString>;
+            stopOnPayment: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    emailTemplate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     provisionedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     lastRequestAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     processedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -52,6 +121,7 @@ declare const journeySchema: z.ZodObject<{
         setup: "setup";
         welcome: "welcome";
         purchase: "purchase";
+        credit_limit: "credit_limit";
     }>;
     version: z.ZodOptional<z.ZodNumber>;
     startsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -79,6 +149,7 @@ declare const messageSchema: z.ZodObject<{
         setup: "setup";
         welcome: "welcome";
         purchase: "purchase";
+        credit_limit: "credit_limit";
     }>>>;
     journeyVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     category: z.ZodOptional<z.ZodEnum<{
@@ -88,11 +159,20 @@ declare const messageSchema: z.ZodObject<{
     from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     replyTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     renderedText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    renderedHtml: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     unsubscribeUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     createdAt: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type CustomerMessageData = z.infer<typeof messageSchema>;
 declare const overviewSchema: z.ZodObject<{
+    funnel: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        title: z.ZodString;
+        stages: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
     space: z.ZodNullable<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
@@ -105,6 +185,33 @@ declare const overviewSchema: z.ZodObject<{
         replyTo: z.ZodNullable<z.ZodString>;
         senderVerified: z.ZodBoolean;
         domainRecords: z.ZodNullable<z.ZodString>;
+        configuration: z.ZodOptional<z.ZodObject<{
+            funnel: z.ZodNullable<z.ZodObject<{
+                title: z.ZodString;
+                stages: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    id: z.ZodString;
+                    label: z.ZodString;
+                    measure: z.ZodLiteral<"event">;
+                    event: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    id: z.ZodString;
+                    label: z.ZodString;
+                    measure: z.ZodLiteral<"first_payment">;
+                }, z.core.$strip>, z.ZodObject<{
+                    id: z.ZodString;
+                    label: z.ZodString;
+                    measure: z.ZodLiteral<"event_after_payment">;
+                    event: z.ZodString;
+                }, z.core.$strip>], "measure">>;
+            }, z.core.$strip>>;
+            followUp: z.ZodNullable<z.ZodObject<{
+                label: z.ZodString;
+                triggerEvent: z.ZodString;
+                prerequisiteEvent: z.ZodNullable<z.ZodString>;
+                stopOnPayment: z.ZodBoolean;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        emailTemplate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         provisionedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         lastRequestAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         processedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -116,6 +223,21 @@ declare const overviewSchema: z.ZodObject<{
         name: z.ZodNullable<z.ZodString>;
         source: z.ZodNullable<z.ZodString>;
         marketingSubscribed: z.ZodBoolean;
+        communicationBasis: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            legacy_account: "legacy_account";
+            explicit_opt_in: "explicit_opt_in";
+            unsubscribed: "unsubscribed";
+        }>>;
+        legacyPolicy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        joinedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        importedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        lastActiveAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        billingStatus: z.ZodOptional<z.ZodEnum<{
+            unknown: "unknown";
+            paid: "paid";
+            free: "free";
+        }>>;
         suppressionReason: z.ZodNullable<z.ZodString>;
         activatedAt: z.ZodNullable<z.ZodString>;
         createdAt: z.ZodNullable<z.ZodString>;
@@ -130,6 +252,7 @@ declare const overviewSchema: z.ZodObject<{
             setup: "setup";
             welcome: "welcome";
             purchase: "purchase";
+            credit_limit: "credit_limit";
         }>;
         version: z.ZodOptional<z.ZodNumber>;
         startsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -156,6 +279,7 @@ declare const overviewSchema: z.ZodObject<{
             setup: "setup";
             welcome: "welcome";
             purchase: "purchase";
+            credit_limit: "credit_limit";
         }>>>;
         journeyVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         category: z.ZodOptional<z.ZodEnum<{
@@ -165,6 +289,7 @@ declare const overviewSchema: z.ZodObject<{
         from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         replyTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         renderedText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        renderedHtml: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         unsubscribeUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         createdAt: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
@@ -176,16 +301,58 @@ export type CustomersOverview = z.infer<typeof overviewSchema>;
 export interface IdentifyCustomerInput {
     externalId: string;
     email: string;
-    name?: string;
+    name?: string | null;
     source?: string;
     billingStatus?: 'unknown' | 'free' | 'paid';
+    /** Original registration time, independent of the Customers record creation time. */
+    joinedAt?: string;
+    lastActiveAt?: string;
+    /** Historical synchronization never enrolls signup journeys. */
+    historical?: boolean;
+    /** Explicit eligibility policy for accounts with unknown preferences; this does not record consent. */
+    legacyPolicy?: string;
+    /** Import known suppressions. Identification can never clear an existing suppression. */
+    suppressionReason?: string;
+    /** Preserve a known unsubscribe atomically during account identification. Never clears an unsubscribe. */
+    unsubscribed?: true;
+    /** Original known unsubscribe time. A later explicit opt-in remains authoritative. */
+    unsubscribedAt?: string;
 }
 export interface CustomerEventInput {
     eventId: string;
     name: string;
+    organizationExternalId?: string;
     occurredAt?: string;
+    /** Preserve activity history without activating or enrolling a customer. */
+    historical?: boolean;
     properties?: Record<string, string | number | boolean | null>;
 }
+export interface CustomerOrganizationInput {
+    externalId: string;
+    name: string;
+    ownerExternalId: string;
+    /** Complete current membership snapshot. The owner is always included. */
+    members: {
+        externalId: string;
+        role: string;
+    }[];
+}
+export interface CustomerPaymentInput {
+    paymentId: string;
+    amountMinor: number;
+    currency: string;
+    paidAt: string;
+    historical?: boolean;
+}
+declare const customerOrganizationSchema: z.ZodObject<{
+    id: z.ZodString;
+    externalId: z.ZodString;
+    name: z.ZodString;
+    ownerCustomerId: z.ZodString;
+    firstPaidAt: z.ZodNullable<z.ZodString>;
+    activatedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type CustomerOrganizationData = z.infer<typeof customerOrganizationSchema>;
 export interface SendCustomerMessageInput {
     requestId: string;
     subject: string;
@@ -196,6 +363,27 @@ export interface SendCustomerMessageInput {
 export declare class CustomerRuntime {
     private readonly client;
     constructor(client: Client);
+    /** Configure this application's event funnel and follow-up rules. Does not activate messaging. */
+    configure(input: CustomerConfiguration & {
+        emailTemplate?: string | null;
+    }): Promise<CustomerConfiguration>;
+    /** Inspect the workspace and environment selected by this app credential. */
+    context(): Promise<{
+        id: string;
+        notebookId: string;
+        mode: CustomerMode;
+    }>;
+    /** Pull due conversion follow-ups, then recheck authoritative billing, credit and access. */
+    pendingFollowUps(): Promise<{
+        messageId: string;
+        organizationExternalId: string;
+        actorExternalId: string;
+    }[]>;
+    /** Eligible deliveries run immediately; expired checks are never reused by a later worker. */
+    resolveFollowUp(messageId: string, resolution: 'eligible' | 'ineligible' | 'paid' | 'credits_available' | 'access_changed'): Promise<CustomerMessageData>;
+    organization(input: CustomerOrganizationInput): Promise<CustomerOrganizationData>;
+    /** Report only server-confirmed positive payments from your existing billing integration. */
+    confirmPayment(organizationExternalId: string, input: CustomerPaymentInput): Promise<CustomerOrganizationData>;
     identify(input: IdentifyCustomerInput): Promise<CustomerData>;
     linkIdentity(customerId: string, externalId: string): Promise<CustomerData>;
     get(customerId: string): Promise<CustomerData>;
@@ -206,6 +394,7 @@ export declare class CustomerRuntime {
     preferences(customerId: string, input: {
         subscribed: boolean;
         source: string;
+        occurredAt?: string;
     }): Promise<CustomerData>;
     send(customerId: string, input: SendCustomerMessageInput): Promise<CustomerMessageData>;
 }

package/dist/customers.js

@@ -1,4 +1,51 @@
+// credit_limit is retained as the compatibility identifier for the application-configured event follow-up.
 import { z } from 'zod';
+const eventName = z.string().trim().min(1).max(100);
+const customerConfigurationSchema = z.object({
+    funnel: z
+        .object({
+        title: z.string().trim().min(1).max(100),
+        stages: z
+            .array(z.discriminatedUnion('measure', [
+            z.object({
+                id: z
+                    .string()
+                    .regex(/^[a-zA-Z0-9_-]+$/)
+                    .max(50),
+                label: z.string().trim().min(1).max(100),
+                measure: z.literal('event'),
+                event: eventName,
+            }),
+            z.object({
+                id: z
+                    .string()
+                    .regex(/^[a-zA-Z0-9_-]+$/)
+                    .max(50),
+                label: z.string().trim().min(1).max(100),
+                measure: z.literal('first_payment'),
+            }),
+            z.object({
+                id: z
+                    .string()
+                    .regex(/^[a-zA-Z0-9_-]+$/)
+                    .max(50),
+                label: z.string().trim().min(1).max(100),
+                measure: z.literal('event_after_payment'),
+                event: eventName,
+            }),
+        ]))
+            .max(12),
+    })
+        .nullable(),
+    followUp: z
+        .object({
+        label: z.string().trim().min(1).max(100),
+        triggerEvent: eventName,
+        prerequisiteEvent: eventName.nullable(),
+        stopOnPayment: z.boolean(),
+    })
+        .nullable(),
+});
 export const customerModeSchema = z.enum(['test', 'live']);
 export const customerSchema = z.object({
     id: z.string(),
@@ -7,6 +54,12 @@ export const customerSchema = z.object({
     name: z.string().nullable(),
     source: z.string().nullable(),
     marketingSubscribed: z.boolean(),
+    communicationBasis: z.enum(['unknown', 'legacy_account', 'explicit_opt_in', 'unsubscribed']).optional(),
+    legacyPolicy: z.string().nullable().optional(),
+    joinedAt: z.string().nullable().optional(),
+    importedAt: z.string().nullable().optional(),
+    lastActiveAt: z.string().nullable().optional(),
+    billingStatus: z.enum(['unknown', 'free', 'paid']).optional(),
     suppressionReason: z.string().nullable(),
     activatedAt: z.string().nullable(),
     createdAt: z.string().nullable(),
@@ -20,6 +73,8 @@ const spaceSchema = z.object({
     replyTo: z.string().nullable(),
     senderVerified: z.boolean(),
     domainRecords: z.string().nullable(),
+    configuration: customerConfigurationSchema.optional(),
+    emailTemplate: z.string().nullable().optional(),
     provisionedAt: z.string().nullable().optional(),
     lastRequestAt: z.string().nullable().optional(),
     processedAt: z.string().nullable().optional(),
@@ -32,7 +87,7 @@ const journeyInputSchema = z.object({
     activationEvent: z.string(),
 });
 const journeySchema = journeyInputSchema.extend({
-    kind: z.enum(['welcome', 'setup', 'purchase']),
+    kind: z.enum(['welcome', 'setup', 'purchase', 'credit_limit']),
     version: z.number().int().optional(),
     startsAt: z.string().nullable().optional(),
     draft: journeyInputSchema.nullable().optional(),
@@ -48,16 +103,21 @@ const messageSchema = z.object({
     dueAt: z.string().nullable().optional(),
     attemptedAt: z.string().nullable().optional(),
     receivedAt: z.string().nullable().optional(),
-    journeyKind: z.enum(['welcome', 'setup', 'purchase']).nullable().optional(),
+    journeyKind: z.enum(['welcome', 'setup', 'purchase', 'credit_limit']).nullable().optional(),
     journeyVersion: z.number().int().nullable().optional(),
     category: z.enum(['marketing', 'service']).optional(),
     from: z.string().nullable().optional(),
     replyTo: z.string().nullable().optional(),
     renderedText: z.string().nullable().optional(),
+    renderedHtml: z.string().nullable().optional(),
     unsubscribeUrl: z.string().nullable().optional(),
     createdAt: z.string().nullable(),
 });
 const overviewSchema = z.object({
+    funnel: z
+        .object({ title: z.string(), stages: z.array(z.object({ id: z.string(), label: z.string(), count: z.number() })) })
+        .nullable()
+        .optional(),
     space: spaceSchema.nullable(),
     customers: z.array(customerSchema),
     journeys: z.array(journeySchema),
@@ -66,11 +126,52 @@ const overviewSchema = z.object({
     messageTotal: z.number().optional(),
     events: z.array(z.string()).optional(),
 });
+const customerOrganizationSchema = z.object({
+    id: z.string(),
+    externalId: z.string(),
+    name: z.string(),
+    ownerCustomerId: z.string(),
+    firstPaidAt: z.string().nullable(),
+    activatedAt: z.string().nullable(),
+});
 /** Use only from trusted app servers with a dedicated Customers credential. */
 export class CustomerRuntime {
     constructor(client) {
         this.client = client;
     }
+    /** Configure this application's event funnel and follow-up rules. Does not activate messaging. */
+    async configure(input) {
+        const configuration = customerConfigurationSchema.parse(input);
+        return customerConfigurationSchema.parse((await this.client.put('/platform/customers/runtime/configuration', {
+            ...configuration,
+            ...(input.emailTemplate !== undefined ? { emailTemplate: input.emailTemplate } : {}),
+        })).data);
+    }
+    /** Inspect the workspace and environment selected by this app credential. */
+    async context() {
+        return z
+            .object({ id: z.string(), notebookId: z.string(), mode: customerModeSchema })
+            .parse((await this.client.get('/platform/customers/runtime/context')).data);
+    }
+    /** Pull due conversion follow-ups, then recheck authoritative billing, credit and access. */
+    async pendingFollowUps() {
+        return z
+            .array(z.object({ messageId: z.string(), organizationExternalId: z.string(), actorExternalId: z.string() }))
+            .parse((await this.client.get('/platform/customers/runtime/follow-ups')).data);
+    }
+    /** Eligible deliveries run immediately; expired checks are never reused by a later worker. */
+    async resolveFollowUp(messageId, resolution) {
+        return messageSchema.parse((await this.client.post(`/platform/customers/runtime/follow-ups/${encodeURIComponent(messageId)}/resolve`, {
+            resolution,
+        })).data);
+    }
+    async organization(input) {
+        return customerOrganizationSchema.parse((await this.client.put('/platform/customers/runtime/organizations', input)).data);
+    }
+    /** Report only server-confirmed positive payments from your existing billing integration. */
+    async confirmPayment(organizationExternalId, input) {
+        return customerOrganizationSchema.parse((await this.client.post(`/platform/customers/runtime/organizations/${encodeURIComponent(organizationExternalId)}/payments`, input)).data);
+    }
     async identify(input) {
         return customerSchema.parse((await this.client.post('/platform/customers/runtime/identify', input)).data);
     }

package/dist/index.d.ts

@@ -288,6 +288,7 @@ export interface NotebookMailData {
     createdAt: string;
     diffForHumans: string;
     html: string | null;
+    text?: string | null;
 }
 export interface NotebookMailStateData {
     enabled: boolean;
@@ -488,6 +489,7 @@ declare class NotebookMail {
         to: string;
         subject: string;
         text: string;
+        html?: string;
     }): Promise<NotebookMailData>;
     enable(): Promise<NotebookMailStateData>;
     disable(): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phpsandbox/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0-canary.0",
   "description": "The TypeScript SDK for PHPSandbox cloud development environments",
   "keywords": [
     "cloud",