@phpsandbox/sdk 0.3.5 → 0.5.0

package/dist/customers.d.ts

@@ -0,0 +1,241 @@
+import { z } from 'zod';
+import type { Client } from './index.js';
+export declare const customerModeSchema: z.ZodEnum<{
+    test: "test";
+    live: "live";
+}>;
+export type CustomerMode = z.infer<typeof customerModeSchema>;
+export declare const customerSchema: z.ZodObject<{
+    id: z.ZodString;
+    externalId: z.ZodString;
+    email: z.ZodString;
+    name: z.ZodNullable<z.ZodString>;
+    source: z.ZodNullable<z.ZodString>;
+    marketingSubscribed: z.ZodBoolean;
+    suppressionReason: z.ZodNullable<z.ZodString>;
+    activatedAt: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type CustomerData = z.infer<typeof customerSchema>;
+declare const spaceSchema: z.ZodObject<{
+    id: z.ZodString;
+    mode: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    enabled: z.ZodBoolean;
+    senderName: z.ZodNullable<z.ZodString>;
+    senderEmail: z.ZodNullable<z.ZodString>;
+    replyTo: z.ZodNullable<z.ZodString>;
+    senderVerified: z.ZodBoolean;
+    domainRecords: 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>>;
+}, z.core.$strip>;
+export type CustomerSpaceData = z.infer<typeof spaceSchema>;
+declare const journeyInputSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    subject: z.ZodString;
+    body: z.ZodString;
+    delayMinutes: z.ZodNumber;
+    activationEvent: z.ZodString;
+}, z.core.$strip>;
+export type CustomerJourneyInput = z.infer<typeof journeyInputSchema>;
+declare const journeySchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    subject: z.ZodString;
+    body: z.ZodString;
+    delayMinutes: z.ZodNumber;
+    activationEvent: z.ZodString;
+    kind: z.ZodEnum<{
+        setup: "setup";
+        welcome: "welcome";
+        purchase: "purchase";
+    }>;
+    version: z.ZodOptional<z.ZodNumber>;
+    startsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    draft: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        subject: z.ZodString;
+        body: z.ZodString;
+        delayMinutes: z.ZodNumber;
+        activationEvent: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CustomerJourneyData = z.infer<typeof journeySchema>;
+declare const messageSchema: z.ZodObject<{
+    id: z.ZodString;
+    customerId: z.ZodNullable<z.ZodString>;
+    recipient: z.ZodString;
+    subject: z.ZodString;
+    body: z.ZodString;
+    status: z.ZodString;
+    error: z.ZodNullable<z.ZodString>;
+    dueAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    attemptedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    receivedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    journeyKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        setup: "setup";
+        welcome: "welcome";
+        purchase: "purchase";
+    }>>>;
+    journeyVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    category: z.ZodOptional<z.ZodEnum<{
+        marketing: "marketing";
+        service: "service";
+    }>>;
+    from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    replyTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    renderedText: 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<{
+    space: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        mode: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        enabled: z.ZodBoolean;
+        senderName: z.ZodNullable<z.ZodString>;
+        senderEmail: z.ZodNullable<z.ZodString>;
+        replyTo: z.ZodNullable<z.ZodString>;
+        senderVerified: z.ZodBoolean;
+        domainRecords: 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>>;
+    }, z.core.$strip>>;
+    customers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        externalId: z.ZodString;
+        email: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        source: z.ZodNullable<z.ZodString>;
+        marketingSubscribed: z.ZodBoolean;
+        suppressionReason: z.ZodNullable<z.ZodString>;
+        activatedAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    journeys: z.ZodArray<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        subject: z.ZodString;
+        body: z.ZodString;
+        delayMinutes: z.ZodNumber;
+        activationEvent: z.ZodString;
+        kind: z.ZodEnum<{
+            setup: "setup";
+            welcome: "welcome";
+            purchase: "purchase";
+        }>;
+        version: z.ZodOptional<z.ZodNumber>;
+        startsAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        draft: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            subject: z.ZodString;
+            body: z.ZodString;
+            delayMinutes: z.ZodNumber;
+            activationEvent: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    messages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        customerId: z.ZodNullable<z.ZodString>;
+        recipient: z.ZodString;
+        subject: z.ZodString;
+        body: z.ZodString;
+        status: z.ZodString;
+        error: z.ZodNullable<z.ZodString>;
+        dueAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        attemptedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        receivedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        journeyKind: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            setup: "setup";
+            welcome: "welcome";
+            purchase: "purchase";
+        }>>>;
+        journeyVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        category: z.ZodOptional<z.ZodEnum<{
+            marketing: "marketing";
+            service: "service";
+        }>>;
+        from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        replyTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        renderedText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        unsubscribeUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        createdAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    messageTotal: z.ZodOptional<z.ZodNumber>;
+    events: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type CustomersOverview = z.infer<typeof overviewSchema>;
+export interface IdentifyCustomerInput {
+    externalId: string;
+    email: string;
+    name?: string;
+    source?: string;
+    billingStatus?: 'unknown' | 'free' | 'paid';
+}
+export interface CustomerEventInput {
+    eventId: string;
+    name: string;
+    occurredAt?: string;
+    properties?: Record<string, string | number | boolean | null>;
+}
+export interface SendCustomerMessageInput {
+    requestId: string;
+    subject: string;
+    body: string;
+    category: 'service' | 'marketing';
+}
+/** Use only from trusted app servers with a dedicated Customers credential. */
+export declare class CustomerRuntime {
+    private readonly client;
+    constructor(client: Client);
+    identify(input: IdentifyCustomerInput): Promise<CustomerData>;
+    linkIdentity(customerId: string, externalId: string): Promise<CustomerData>;
+    get(customerId: string): Promise<CustomerData>;
+    event(customerId: string, input: CustomerEventInput): Promise<{
+        id: string;
+        name: string;
+    }>;
+    preferences(customerId: string, input: {
+        subscribed: boolean;
+        source: string;
+    }): Promise<CustomerData>;
+    send(customerId: string, input: SendCustomerMessageInput): Promise<CustomerMessageData>;
+}
+export declare class CustomersApi {
+    private readonly client;
+    readonly runtime: CustomerRuntime;
+    constructor(client: Client);
+    forNotebook(notebookId: string): NotebookCustomers;
+}
+export declare class NotebookCustomers {
+    private readonly notebookId;
+    private readonly client;
+    constructor(notebookId: string, client: Client);
+    list(mode?: CustomerMode, query?: {
+        search?: string;
+        page?: number;
+        messagePage?: number;
+    }): Promise<CustomersOverview>;
+    connect(mode?: CustomerMode): Promise<CustomerSpaceData>;
+    provision(mode?: CustomerMode): Promise<CustomerSpaceData>;
+    disable(mode?: CustomerMode): Promise<CustomerSpaceData>;
+    resume(mode?: CustomerMode): Promise<CustomerSpaceData>;
+    rotate(mode?: CustomerMode): Promise<CustomerSpaceData>;
+    sender(input: {
+        senderName: string;
+        senderEmail: string;
+        replyTo: string;
+    }, mode?: CustomerMode): Promise<CustomerSpaceData>;
+    verifySender(mode?: CustomerMode): Promise<CustomerSpaceData>;
+    journey(kind: CustomerJourneyData['kind'], input: CustomerJourneyInput, mode?: CustomerMode): Promise<CustomerJourneyData>;
+    private path;
+}
+export {};

package/dist/customers.js

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+export const customerModeSchema = z.enum(['test', 'live']);
+export const customerSchema = z.object({
+    id: z.string(),
+    externalId: z.string(),
+    email: z.string(),
+    name: z.string().nullable(),
+    source: z.string().nullable(),
+    marketingSubscribed: z.boolean(),
+    suppressionReason: z.string().nullable(),
+    activatedAt: z.string().nullable(),
+    createdAt: z.string().nullable(),
+});
+const spaceSchema = z.object({
+    id: z.string(),
+    mode: customerModeSchema,
+    enabled: z.boolean(),
+    senderName: z.string().nullable(),
+    senderEmail: z.string().nullable(),
+    replyTo: z.string().nullable(),
+    senderVerified: z.boolean(),
+    domainRecords: z.string().nullable(),
+    provisionedAt: z.string().nullable().optional(),
+    lastRequestAt: z.string().nullable().optional(),
+    processedAt: z.string().nullable().optional(),
+});
+const journeyInputSchema = z.object({
+    enabled: z.boolean(),
+    subject: z.string(),
+    body: z.string(),
+    delayMinutes: z.number(),
+    activationEvent: z.string(),
+});
+const journeySchema = journeyInputSchema.extend({
+    kind: z.enum(['welcome', 'setup', 'purchase']),
+    version: z.number().int().optional(),
+    startsAt: z.string().nullable().optional(),
+    draft: journeyInputSchema.nullable().optional(),
+});
+const messageSchema = z.object({
+    id: z.string(),
+    customerId: z.string().nullable(),
+    recipient: z.string(),
+    subject: z.string(),
+    body: z.string(),
+    status: z.string(),
+    error: z.string().nullable(),
+    dueAt: z.string().nullable().optional(),
+    attemptedAt: z.string().nullable().optional(),
+    receivedAt: z.string().nullable().optional(),
+    journeyKind: z.enum(['welcome', 'setup', 'purchase']).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(),
+    unsubscribeUrl: z.string().nullable().optional(),
+    createdAt: z.string().nullable(),
+});
+const overviewSchema = z.object({
+    space: spaceSchema.nullable(),
+    customers: z.array(customerSchema),
+    journeys: z.array(journeySchema),
+    messages: z.array(messageSchema),
+    total: z.number(),
+    messageTotal: z.number().optional(),
+    events: z.array(z.string()).optional(),
+});
+/** Use only from trusted app servers with a dedicated Customers credential. */
+export class CustomerRuntime {
+    constructor(client) {
+        this.client = client;
+    }
+    async identify(input) {
+        return customerSchema.parse((await this.client.post('/platform/customers/runtime/identify', input)).data);
+    }
+    async linkIdentity(customerId, externalId) {
+        return customerSchema.parse((await this.client.post(`/platform/customers/runtime/${encodeURIComponent(customerId)}/identities`, {
+            externalId,
+        })).data);
+    }
+    async get(customerId) {
+        return customerSchema.parse((await this.client.get(`/platform/customers/runtime/${encodeURIComponent(customerId)}`)).data);
+    }
+    async event(customerId, input) {
+        return z
+            .object({ id: z.string(), name: z.string() })
+            .parse((await this.client.post(`/platform/customers/runtime/${encodeURIComponent(customerId)}/events`, input)).data);
+    }
+    async preferences(customerId, input) {
+        return customerSchema.parse((await this.client.put(`/platform/customers/runtime/${encodeURIComponent(customerId)}/preferences`, input)).data);
+    }
+    async send(customerId, input) {
+        return messageSchema.parse((await this.client.post(`/platform/customers/runtime/${encodeURIComponent(customerId)}/messages`, input)).data);
+    }
+}
+export class CustomersApi {
+    constructor(client) {
+        this.client = client;
+        this.runtime = new CustomerRuntime(client);
+    }
+    forNotebook(notebookId) {
+        return new NotebookCustomers(notebookId, this.client);
+    }
+}
+export class NotebookCustomers {
+    constructor(notebookId, client) {
+        this.notebookId = notebookId;
+        this.client = client;
+    }
+    async list(mode = 'test', query = {}) {
+        return overviewSchema.parse((await this.client.get(`${this.path(mode)}?${new URLSearchParams(Object.entries(query).map(([key, value]) => [key, String(value)])).toString()}`)).data);
+    }
+    async connect(mode = 'test') {
+        return spaceSchema.parse((await this.client.put(this.path(mode), {})).data);
+    }
+    async provision(mode = 'test') {
+        return spaceSchema.parse((await this.client.post(`${this.path(mode)}/provision`, {})).data);
+    }
+    async disable(mode = 'test') {
+        return spaceSchema.parse((await this.client.post(`${this.path(mode)}/disable`, {})).data);
+    }
+    async resume(mode = 'test') {
+        return spaceSchema.parse((await this.client.post(`${this.path(mode)}/resume`, {})).data);
+    }
+    async rotate(mode = 'test') {
+        return spaceSchema.parse((await this.client.post(`${this.path(mode)}/rotate`, {})).data);
+    }
+    async sender(input, mode = 'test') {
+        return spaceSchema.parse((await this.client.put(`${this.path(mode)}/sender`, input)).data);
+    }
+    async verifySender(mode = 'test') {
+        return spaceSchema.parse((await this.client.post(`${this.path(mode)}/sender/verify`, {})).data);
+    }
+    async journey(kind, input, mode = 'test') {
+        return journeySchema.parse((await this.client.put(`${this.path(mode)}/journeys/${kind}`, input)).data);
+    }
+    path(mode) {
+        return `/platform/customers/sandboxes/${encodeURIComponent(this.notebookId)}/${mode}`;
+    }
+}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { AppRuntime, type AppRuntimeOptions } from './app.js';
+export { AppRuntime };
+export type { AppRuntimeOptions };
 import { type Identity } from './identity.js';
 export type { Identity } from './identity.js';
 import { NotebookPublication } from './publication/index.js';
@@ -18,6 +21,10 @@ import { PublicationApi } from './publication/index.js';
 import { ServerApi } from './servers.js';
 import { Feedback } from './feedback.js';
 import { IntegrationApi, SandboxIntegrationApi } from './integrations/index.js';
+import { PaymentsApi, NotebookPayments } from './payments.js';
+import { CustomersApi } from './customers.js';
+export * from './customers.js';
+export * from './payments.js';
 export type { Disposable } from './types.js';
 export { LspConnection } from './lsp.js';
 export { FileChangeFilter, FileChangeType, FileType } from './filesystem.js';
@@ -172,6 +179,8 @@ export interface NotebookSecretData {
     name: string;
     type: SecretType;
     environment: SecretEnvironment;
+    managedBy?: string | null;
+    inheritOnFork?: boolean;
     createdAt: string | null;
     updatedAt: string | null;
 }
@@ -179,6 +188,9 @@ export interface NotebookSecretListOptions {
     environment?: SecretEnvironment;
 }
 export interface UpsertNotebookSecretInput {
+    /** Platform-owned secrets cannot be inherited by forks. Requires a platform credential. */
+    managed?: boolean;
+    inheritOnFork?: boolean;
     value: string;
     type?: SecretType;
     environment?: SecretEnvironment;
@@ -329,6 +341,8 @@ declare class ClientImplementation {
     readonly publications: PublicationApi;
     readonly servers: ServerApi;
     readonly integrations: IntegrationApi;
+    readonly payments: PaymentsApi;
+    readonly customers: CustomersApi;
     readonly options: PHPSandboxClientOptions;
     private readonly runtimeTransportValue;
     get runtimeTransport(): RuntimeTransport;
@@ -364,9 +378,12 @@ export declare class PHPSandbox {
     readonly publications: PublicationApi;
     readonly servers: ServerApi;
     readonly integrations: IntegrationApi;
+    readonly payments: PaymentsApi;
+    readonly customers: CustomersApi;
     private constructor();
     whoami(): Promise<Identity>;
     get runtimeTransport(): RuntimeTransport;
+    static app(options?: AppRuntimeOptions): AppRuntime;
     static realtime(token: string, url?: string, options?: PHPSandboxClientOptions): PHPSandbox;
     static rest(token: string, url?: string, options?: PHPSandboxClientOptions): PHPSandbox;
 }
@@ -399,6 +416,7 @@ export declare class NotebookInstance {
     readonly config: Config;
     readonly secrets: NotebookSecrets;
     readonly integrations: SandboxIntegrationApi;
+    readonly payments: NotebookPayments;
     readonly preview: NotebookPreview;
     readonly mail: NotebookMail;
     readonly feedback: Feedback;
@@ -462,6 +480,15 @@ declare class NotebookMail {
     private readonly notebookId;
     constructor(client: Client, notebookId: string);
     status(): Promise<NotebookMailStateData>;
+    /** Capture a platform-generated development email in the notebook inbox. Never sends externally. */
+    capture(input: {
+        requestId: string;
+        from: string;
+        fromName: string;
+        to: string;
+        subject: string;
+        text: string;
+    }): Promise<NotebookMailData>;
     enable(): Promise<NotebookMailStateData>;
     disable(): Promise<void>;
     list(options?: NotebookMailListOptions): Promise<PaginatedApiResponse<NotebookMailData>>;

package/dist/index.js

@@ -10,6 +10,8 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
 var _NotebookInstance_instances, _NotebookInstance_initPromise, _NotebookInstance_init;
+import { AppRuntime, resolveAppConfiguration } from './app.js';
+export { AppRuntime };
 import { identitySchema } from './identity.js';
 import { NotebookPublication } from './publication/index.js';
 import { Filesystem } from './filesystem.js';
@@ -31,6 +33,10 @@ import { RestRuntimeInvoker } from './runtime/rest.js';
 import { Feedback } from './feedback.js';
 import { IntegrationApi, SandboxIntegrationApi } from './integrations/index.js';
 import { authenticatedRequest } from './http.js';
+import { PaymentsApi, NotebookPayments } from './payments.js';
+import { CustomersApi } from './customers.js';
+export * from './customers.js';
+export * from './payments.js';
 export { LspConnection } from './lsp.js';
 export { FileChangeFilter, FileChangeType, FileType } from './filesystem.js';
 export { notebookBuiltinServices, notebookKnownServices } from './services.js';
@@ -86,6 +92,8 @@ class ClientImplementation {
         this.notebook = new NotebookApi(this);
         this.servers = new ServerApi(this);
         this.integrations = new IntegrationApi(this);
+        this.payments = new PaymentsApi(this);
+        this.customers = new CustomersApi(this);
         this.options = { ...options };
         this.runtimeTransportValue = runtimeTransport;
         this.baseUrl = normalizeApiBaseUrl(url);
@@ -220,6 +228,8 @@ export class PHPSandbox {
         this.publications = client.publications;
         this.servers = client.servers;
         this.integrations = client.integrations;
+        this.payments = client.payments;
+        this.customers = client.customers;
     }
     async whoami() {
         const { data } = await this.client.get('/auth/whoami');
@@ -232,6 +242,10 @@ export class PHPSandbox {
     get runtimeTransport() {
         return this.client.runtimeTransport;
     }
+    static app(options = {}) {
+        const { token, url, mode } = resolveAppConfiguration(options);
+        return new AppRuntime(new ClientImplementation(token, url, {}, 'rest'), token, mode);
+    }
     static realtime(token, url = 'https://api.phpsandbox.io/v1', options = {}) {
         return new PHPSandbox(new ClientImplementation(token, url, options));
     }
@@ -287,6 +301,7 @@ export class NotebookInstance {
         this.config = new Config(this);
         this.secrets = new NotebookSecrets(client, this.data.id);
         this.integrations = new SandboxIntegrationApi(this.data.id, client);
+        this.payments = new NotebookPayments(this.data.id, client);
         this.preview = new NotebookPreview(client, this.data.id);
         this.mail = new NotebookMail(client, this.data.id);
         this.feedback = new Feedback(client, this.data.id);
@@ -593,6 +608,11 @@ class NotebookMail {
         const response = await this.client.get(`/notebook/${this.notebookId}/mail`);
         return response.data;
     }
+    /** Capture a platform-generated development email in the notebook inbox. Never sends externally. */
+    async capture(input) {
+        const response = await this.client.post(`/notebook/${this.notebookId}/mails`, input);
+        return response.data;
+    }
     async enable() {
         const response = await this.client.put(`/notebook/${this.notebookId}/mail`);
         return response.data;