@phpsandbox/sdk 0.4.0 → 0.5.0

package/README.md

@@ -55,6 +55,33 @@ 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 }`.
+
+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.
+
 ## Server invitations
 
 Server administrators can invite someone by email and inspect the shared invitation state:
@@ -309,6 +336,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 });
+    }
+}