@phpsandbox/sdk 0.5.0 → 0.6.0-canary.1

package/README.md

@@ -80,8 +80,30 @@ const checkout = await platform.payments.checkout({
 
 Persist an opaque UUID on each app account for its external customer identity; separate databases must not reuse sequential IDs. Initialize this client only on the app server. It reads the provisioned app configuration and exposes only app runtime capabilities, without notebook or organization administration. Production uses its own identity and never falls back to development. Select `{ mode: 'test' }` once for an intentional sandbox run. Runtimes without `process.env` can supply server bindings through `{ env }`.
 
+Applications can configure their own organization conversion stages and one event follow-up. Configuration never activates a journey:
+
+```ts
+await app.customers.configure({
+  funnel: {
+    title: 'Learning outcomes',
+    stages: [{ id: 'lesson', label: 'Completed a lesson', measure: 'event', event: 'lesson.completed' }],
+  },
+  followUp: { label: 'Help learners', triggerEvent: 'lesson.stalled', prerequisiteEvent: null, stopOnPayment: false },
+  emailTemplate: '<html><body><h1>{{subject}}</h1><main>{{content}}</main></body></html>',
+});
+```
+
+Stages support `event`, `first_payment`, and `event_after_payment` measures. Historical imports never count as new conversions or trigger event follow-ups. The existing `credit_limit` journey identifier is retained for compatibility; its trigger, prerequisite and payment rule now come from application configuration, while its delay and reviewed content remain journey settings. Pause the journey before changing its rules, then review and activate it separately. Due follow-ups require a fresh application eligibility resolution through `pendingFollowUps()` and `resolveFollowUp()`.
+
+HTML templates support escaped `subject`, `content`, `name`, `email` and `unsubscribeUrl` placeholders; `content` is required. Plain text remains available, and marketing messages always receive an unsubscribe footer. Set `emailTemplate: null` to use plain text. Queued messages and reviewed campaigns preserve their selected design. Production currently uses a fixed platform From address; display name and Reply-To are configurable. Custom sending domains are not supported.
+
+
 Verify incoming payment callbacks with `platform.payments.verifyEvent(rawBody, signature)`, passing the `phpsandbox-signature` header. The client verifies the original bytes, timestamp and environment before returning the event; the app must still validate order ownership and apply revisions idempotently.
 
+Application Customers also supports historical identification (`historical`, `joinedAt`, `lastActiveAt`), separate legacy-account eligibility (`legacyPolicy`), known unsubscribes and suppressions, organization membership snapshots, and confirmed positive payments from existing billing. Use `customers.organization()` to synchronize relationships and `customers.confirmPayment()` only after backend provider verification. Historical payments never create first-payment conversions.
+
+For approved credit-limit journeys, an application worker pulls `customers.pendingFollowUps()`, rechecks authoritative payment, access and actual credits, then immediately calls `customers.resolveFollowUp()`. Delivery rechecks contact eligibility and requires a fresh application decision. Keep original preference timestamps with `customers.preferences(..., { subscribed, source, occurredAt })`; a legacy policy does not fabricate consent.
+
 ## Server invitations
 
 Server administrators can invite someone by email and inspect the shared invitation state:

package/dist/browser/phpsandbox-sdk.esm.js

@@ -14527,6 +14527,39 @@ function date4(params) {
 config(en_default());
 
 // src/customers.ts
+var eventName = external_exports.string().trim().min(1).max(100);
+var customerConfigurationSchema = external_exports.object({
+  funnel: external_exports.object({
+    title: external_exports.string().trim().min(1).max(100),
+    stages: external_exports.array(
+      external_exports.discriminatedUnion("measure", [
+        external_exports.object({
+          id: external_exports.string().regex(/^[a-zA-Z0-9_-]+$/).max(50),
+          label: external_exports.string().trim().min(1).max(100),
+          measure: external_exports.literal("event"),
+          event: eventName
+        }),
+        external_exports.object({
+          id: external_exports.string().regex(/^[a-zA-Z0-9_-]+$/).max(50),
+          label: external_exports.string().trim().min(1).max(100),
+          measure: external_exports.literal("first_payment")
+        }),
+        external_exports.object({
+          id: external_exports.string().regex(/^[a-zA-Z0-9_-]+$/).max(50),
+          label: external_exports.string().trim().min(1).max(100),
+          measure: external_exports.literal("event_after_payment"),
+          event: eventName
+        })
+      ])
+    ).max(12)
+  }).nullable(),
+  followUp: external_exports.object({
+    label: external_exports.string().trim().min(1).max(100),
+    triggerEvent: eventName,
+    prerequisiteEvent: eventName.nullable(),
+    stopOnPayment: external_exports.boolean()
+  }).nullable()
+});
 var customerModeSchema = external_exports.enum(["test", "live"]);
 var customerSchema = external_exports.object({
   id: external_exports.string(),
@@ -14535,6 +14568,12 @@ var customerSchema = external_exports.object({
   name: external_exports.string().nullable(),
   source: external_exports.string().nullable(),
   marketingSubscribed: external_exports.boolean(),
+  communicationBasis: external_exports.enum(["unknown", "legacy_account", "explicit_opt_in", "unsubscribed"]).optional(),
+  legacyPolicy: external_exports.string().nullable().optional(),
+  joinedAt: external_exports.string().nullable().optional(),
+  importedAt: external_exports.string().nullable().optional(),
+  lastActiveAt: external_exports.string().nullable().optional(),
+  billingStatus: external_exports.enum(["unknown", "free", "paid"]).optional(),
   suppressionReason: external_exports.string().nullable(),
   activatedAt: external_exports.string().nullable(),
   createdAt: external_exports.string().nullable()
@@ -14548,6 +14587,8 @@ var spaceSchema = external_exports.object({
   replyTo: external_exports.string().nullable(),
   senderVerified: external_exports.boolean(),
   domainRecords: external_exports.string().nullable(),
+  configuration: customerConfigurationSchema.optional(),
+  emailTemplate: external_exports.string().nullable().optional(),
   provisionedAt: external_exports.string().nullable().optional(),
   lastRequestAt: external_exports.string().nullable().optional(),
   processedAt: external_exports.string().nullable().optional()
@@ -14560,7 +14601,7 @@ var journeyInputSchema = external_exports.object({
   activationEvent: external_exports.string()
 });
 var journeySchema = journeyInputSchema.extend({
-  kind: external_exports.enum(["welcome", "setup", "purchase"]),
+  kind: external_exports.enum(["welcome", "setup", "purchase", "credit_limit"]),
   version: external_exports.number().int().optional(),
   startsAt: external_exports.string().nullable().optional(),
   draft: journeyInputSchema.nullable().optional()
@@ -14576,16 +14617,18 @@ var messageSchema = external_exports.object({
   dueAt: external_exports.string().nullable().optional(),
   attemptedAt: external_exports.string().nullable().optional(),
   receivedAt: external_exports.string().nullable().optional(),
-  journeyKind: external_exports.enum(["welcome", "setup", "purchase"]).nullable().optional(),
+  journeyKind: external_exports.enum(["welcome", "setup", "purchase", "credit_limit"]).nullable().optional(),
   journeyVersion: external_exports.number().int().nullable().optional(),
   category: external_exports.enum(["marketing", "service"]).optional(),
   from: external_exports.string().nullable().optional(),
   replyTo: external_exports.string().nullable().optional(),
   renderedText: external_exports.string().nullable().optional(),
+  renderedHtml: external_exports.string().nullable().optional(),
   unsubscribeUrl: external_exports.string().nullable().optional(),
   createdAt: external_exports.string().nullable()
 });
 var overviewSchema = external_exports.object({
+  funnel: external_exports.object({ title: external_exports.string(), stages: external_exports.array(external_exports.object({ id: external_exports.string(), label: external_exports.string(), count: external_exports.number() })) }).nullable().optional(),
   space: spaceSchema.nullable(),
   customers: external_exports.array(customerSchema),
   journeys: external_exports.array(journeySchema),
@@ -14594,10 +14637,58 @@ var overviewSchema = external_exports.object({
   messageTotal: external_exports.number().optional(),
   events: external_exports.array(external_exports.string()).optional()
 });
+var customerOrganizationSchema = external_exports.object({
+  id: external_exports.string(),
+  externalId: external_exports.string(),
+  name: external_exports.string(),
+  ownerCustomerId: external_exports.string(),
+  firstPaidAt: external_exports.string().nullable(),
+  activatedAt: external_exports.string().nullable()
+});
 var CustomerRuntime = class {
   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 !== void 0 ? { emailTemplate: input.emailTemplate } : {}
+      })).data
+    );
+  }
+  /** Inspect the workspace and environment selected by this app credential. */
+  async context() {
+    return external_exports.object({ id: external_exports.string(), notebookId: external_exports.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 external_exports.array(external_exports.object({ messageId: external_exports.string(), organizationExternalId: external_exports.string(), actorExternalId: external_exports.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);
   }
@@ -15242,14 +15333,14 @@ async function* readPublicationStream(input, options = {}) {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
   let buffer = "";
-  let eventName = "message";
+  let eventName2 = "message";
   let data = [];
   let ended = false;
   let receivedResult = false;
   function dispatch() {
-    const name = eventName;
+    const name = eventName2;
     const lines = data;
-    eventName = "message";
+    eventName2 = "message";
     data = [];
     if (!lines.length || !PublishStreamSseEventNameSchema.safeParse(name).success) {
       return null;
@@ -15281,7 +15372,7 @@ async function* readPublicationStream(input, options = {}) {
       content = content.slice(1);
     }
     if (field === "event") {
-      eventName = content;
+      eventName2 = content;
     }
     if (field === "data") {
       data.push(content);