@phpsandbox/sdk 0.4.0 → 0.6.0-canary.0

package/README.md

@@ -55,6 +55,55 @@ PHPSandbox.rest('token', 'https://api.phpsandbox.io/v1', {
 });
 ```
 
+## App server integration
+
+Apps hosted on PHPSandbox can use one environment-scoped identity for Customers and Payments:
+
+```ts
+import { PHPSandbox } from '@phpsandbox/sdk';
+
+const platform = PHPSandbox.app();
+const customer = await platform.customers.identify({
+  externalId: account.customerExternalId,
+  email: account.email,
+  billingStatus: account.hasSubscription ? 'paid' : 'free',
+});
+const checkout = await platform.payments.checkout({
+  customerId: customer.id,
+  requestId: order.requestId,
+  orderId: order.id,
+  priceId: order.priceId,
+  successPath: '/thanks',
+  cancelPath: '/account',
+});
+```
+
+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:
@@ -309,6 +358,16 @@ if (!state.enabled) {
   await notebook.mail.enable();
 }
 
+// Capture a development email in the notebook inbox without external delivery.
+await notebook.mail.capture({
+  requestId: crypto.randomUUID(),
+  from: 'hello@example.com',
+  fromName: 'Example app',
+  to: 'alex@example.com',
+  subject: 'Welcome',
+  text: 'Hello Alex',
+});
+
 const mails = await notebook.mail.list();
 const mail = await notebook.mail.get(mails.data[0].hash);
 

package/dist/app.d.ts

@@ -0,0 +1,21 @@
+import type { Client } from './index.js';
+import { CustomerRuntime } from './customers.js';
+import { PaymentRuntime, type PaymentMode } from './payments.js';
+export interface AppRuntimeOptions {
+    /** Defaults to live in production and test otherwise. There is no fallback between modes. */
+    mode?: PaymentMode;
+    /** Supply server bindings explicitly on runtimes without process.env. */
+    env?: Record<string, string | undefined>;
+}
+export declare function resolveAppConfiguration(options: AppRuntimeOptions): {
+    mode: "test" | "live";
+    token: string;
+    url: string;
+};
+/** Scoped app-server APIs. Organization and workspace management are deliberately excluded. */
+export declare class AppRuntime {
+    readonly mode: PaymentMode;
+    readonly customers: CustomerRuntime;
+    readonly payments: PaymentRuntime;
+    constructor(client: Client, token: string, mode: PaymentMode);
+}

package/dist/app.js

@@ -0,0 +1,23 @@
+import { CustomerRuntime } from './customers.js';
+import { PaymentRuntime } from './payments.js';
+export function resolveAppConfiguration(options) {
+    if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+        throw new Error('Application credentials must only be used on a trusted server.');
+    }
+    const environment = options.env ?? (typeof process === 'undefined' ? {} : process.env);
+    const mode = options.mode ?? (environment.NODE_ENV === 'production' ? 'live' : 'test');
+    const token = environment[`PHPSANDBOX_APP_${mode.toUpperCase()}_TOKEN`];
+    const url = environment.PHPSANDBOX_APP_API_URL;
+    if (!token || !/^happ_[a-f0-9]{64}$/.test(token) || !url) {
+        throw new Error(`Connect your app's ${mode === 'live' ? 'production' : 'development'} platform environment before using Customers or Payments.`);
+    }
+    return { mode, token, url };
+}
+/** Scoped app-server APIs. Organization and workspace management are deliberately excluded. */
+export class AppRuntime {
+    constructor(client, token, mode) {
+        this.mode = mode;
+        this.customers = new CustomerRuntime(client);
+        this.payments = new PaymentRuntime(client, { token, mode });
+    }
+}