@funnelchat-hq/sandbox 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { ConfigError, parseArgs, VERSION, DEFAULT_PORT, DEFAULT_CONFIG_FILE, resolveConfig, createSandbox } from './chunk-PF4CGK6J.js';
+import { ConfigError, parseArgs, VERSION, DEFAULT_PORT, DEFAULT_CONFIG_FILE, resolveConfig, createSandbox } from './chunk-M5E6NAXM.js';
 
 // src/cli.ts
 var HELP = `funnelchat-sandbox ${VERSION}
@@ -10,6 +10,7 @@ Usage: npx funnelchat-sandbox [options]
 Options:
   -p, --port <n>                 Port (default ${DEFAULT_PORT}; 0 takes a free one).
       --host <host>              Where to listen (default 127.0.0.1; in Docker, 0.0.0.0).
+      --public-url <url>         Base URL of the sign-up links (default: where it listens; in Docker, the published one).
   -c, --config <file>            JSON configuration (default ./${DEFAULT_CONFIG_FILE}, if it exists).
       --status-delays <s,d,r>    Seconds until sent, delivered and read (default 1,2,3; "-" stops there).
       --retry-delays <a,b,c>     Seconds between retries of a webhook (default 60,300,1800).
@@ -19,6 +20,7 @@ Options:
       --no-antiblock             Do not apply the spam brakes.
       --no-rate-limit            Do not apply the per-number pace.
       --template-approval <s>    Seconds until a new template is approved (default 5; "-" leaves it pending).
+      --meta-connect             Turn on the Meta sign-up by link (off by default, like production).
   -q, --quiet                    No line per request and per delivery.
   -h, --help                     This help.
   -v, --version                  The version.

package/dist/index.d.ts

@@ -41,6 +41,30 @@ interface SandboxConfig {
     templateApprovalSeconds: number | null;
     /** Subscriptions to create at start and after every reset. */
     subscriptions: PresetSubscription[];
+    /**
+     * The number quota of the account and the Meta sign-up switch; `POST /_sandbox/numbers` changes them while it runs.
+     * QR and Meta of the same phone count once; the two example numbers already use two places.
+     */
+    numbers: {
+        /** Numbers the plan allows: `403 number_limit_reached` beyond it. */
+        limit: number;
+        /** `false`: the plan has no numbers, `403 numbers_not_included`. */
+        included: boolean;
+        /** A trial account: one number of the US pool instead of three. */
+        trial: boolean;
+        /**
+         * The Meta sign-up by link. `false` (the default, like production until the domain is registered with Meta):
+         * `POST /connect-links` with `type: meta` and its page answer `503 meta_connect_disabled`. Turn it on to test it.
+         */
+        metaConnect: boolean;
+        /** `POST /connect-links` per minute (accounts: 10); one more answers Laravel's `429 Too Many Attempts.`. */
+        linksPerMinute: number;
+    };
+    /**
+     * Where the sign-up page is reachable, for the `url` of a link (`<publicUrl>/connect/<token>`). Never taken from the
+     * request's `Host`. `null`: the address the sandbox listens on.
+     */
+    publicUrl: string | null;
     /** How many requests and deliveries the panel keeps. */
     historyLimit: number;
     /** One line per request and per delivery on the console. */
@@ -60,18 +84,65 @@ interface MessageError {
     reason: string | null;
 }
 type DeviceKind = 'cloud' | 'qr';
+/** The aggregated health of an official number (accounts `MetaHealthStatusService`). */
+type HealthState = 'available' | 'limited' | 'blocked' | 'unknown';
 interface Device {
     id: number;
     alias: string;
-    /** Digits only, without `+`. */
-    number: string;
+    /** Digits only, without `+`. `null` while a number created by QR has not been scanned. */
+    number: string | null;
     /** WhatsAppProviderEnum of accounts: 1 Z-API (QR), 2 WhatsApp Cloud (official). */
     provider: 1 | 2;
     kind: DeviceKind;
     connected: boolean;
+    /** Official numbers only: it shares the number with the WhatsApp Business app. */
+    coexistence: boolean;
+    /** Official numbers only: it came from the pool of US numbers. */
+    fromPool: boolean;
+    /** Free text of the integrator, up to 255 characters, not unique. */
+    externalReference: string | null;
+    /** Official numbers only (`null` for QR). */
+    health: HealthState | null;
+    /** The sign-up link that connected it last: `connect_link_id` of every `device.*` event. */
+    lastConnectLinkId: number | null;
     wabaId: string | null;
     phoneNumberId: string | null;
+    firstConnectedAt: Date | null;
+    createdAt: Date;
+}
+type ConnectLinkStatus = 'pending' | 'completed' | 'failed' | 'expired' | 'revoked';
+/** A sign-up link (contract A1 `connect-links`): it creates (or reconnects) a number when the page completes. */
+interface ConnectLink {
+    id: number;
+    type: 'meta' | 'qr';
+    status: ConnectLinkStatus;
+    /** sha256 of the token: the raw token is only in the `url` of the create answer. */
+    tokenHash: string;
+    allowedConnectionTypes: ('coexistence' | 'dedicated')[] | null;
+    provisionUsNumber: boolean;
+    /** `qr` only, without `device_id`: the country of the phone (two letters, lower case), where the session opens. */
+    country: string | null;
+    /** Reconnects this number; otherwise `null` until the link completes, then the number it created. */
+    deviceId: number | null;
+    reconnect: boolean;
+    /** `qr` only: adds QR to this number in coexistence. Not part of the public resource. */
+    sameNumberAs: number | null;
+    externalReference: string | null;
+    returnUrl: string | null;
+    errorCode: string | null;
+    /** Failed attempts of Facebook or Meta: at the fifth the link ends `failed`. */
+    failedAttempts: number;
+    expiresAt: Date;
     createdAt: Date;
+    completedAt: Date | null;
+}
+/** An answer kept under an `Idempotency-Key` for 24 hours. */
+interface IdempotentAnswer {
+    fingerprint: string;
+    status: number;
+    body: unknown;
+    headers: Record<string, string>;
+    storedAt: Date;
 }
 interface Contact {
     id: number;
@@ -287,6 +358,19 @@ declare class Store {
     forms: Map<number, FormVersion>;
     formFamilies: Map<number, FormFamily>;
     formRuns: Map<number, FormRun>;
+    connectLinks: Map<number, ConnectLink>;
+    /** When each `POST /connect-links` arrived in the last minute: the per-minute limit. */
+    linkAttempts: number[];
+    /** Answers by `Idempotency-Key`, per resource (`devices`, `connect-links`): one account. */
+    idempotency: Map<string, IdempotentAnswer>;
+    /** The number quota of the account and the switch of the Meta sign-up (`POST /_sandbox/numbers`). */
+    numbers: {
+        limit: number;
+        included: boolean;
+        trial: boolean;
+        metaConnect: boolean;
+        linksPerMinute: number;
+    };
     /** Last inbound message per `contactId:deviceId`: the 24-hour window. */
     lastInbound: Map<string, Date>;
     /** API-key sends per contact since its last inbound message: the antiblock counters. */
@@ -317,6 +401,8 @@ declare class Store {
         formFamily: Sequence;
         formVersion: Sequence;
         formRun: Sequence;
+        device: Sequence;
+        connectLink: Sequence;
     };
     constructor(historyLimit?: number);
     logRequest(entry: Omit<RequestLogEntry, 'id'>): RequestLogEntry;
@@ -398,7 +484,11 @@ declare class SandboxApp {
     readonly webhooks: Webhooks;
     /** Grows on every reset, so work started before a reset does not touch the new state. */
     generation: number;
+    /** The address the sandbox listens on, once it does: the host of the sign-up links when `publicUrl` is not set. */
+    listenUrl: string | null;
     constructor(config: SandboxConfig, logger?: Logger);
+    /** `http://host:port` of the sign-up page: `publicUrl`, or where the sandbox listens. */
+    get publicUrl(): string;
     private populate;
     /** `POST /_sandbox/reset`: empty state, the example data again, timers cancelled. */
     reset(): void;

package/dist/index.js

@@ -1,3 +1,3 @@
-export { DELIVERY_HEADER, EDGE_ERRORS, EVENT_HEADER, FAILURE_REASONS, FORM_TEMPLATES, META_ERRORS, REJECTIONS, REQUEST_ID_HEADER, SEND_FILE_TYPES, SIGNATURE_HEADER, SUPPORTED_EXTENSIONS, VERSION, catalog, createSandbox, defaultConfig, mergeConfig, signature } from './chunk-PF4CGK6J.js';
+export { DELIVERY_HEADER, EDGE_ERRORS, EVENT_HEADER, FAILURE_REASONS, FORM_TEMPLATES, META_ERRORS, REJECTIONS, REQUEST_ID_HEADER, SEND_FILE_TYPES, SIGNATURE_HEADER, SUPPORTED_EXTENSIONS, VERSION, catalog, createSandbox, defaultConfig, mergeConfig, signature } from './chunk-M5E6NAXM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/funnelchat-sandbox.config.example.json

@@ -4,6 +4,8 @@
   "webhooks": { "retryDelays": [5, 15, 30], "timeoutSeconds": 10 },
   "rules": { "window": true, "antiblock": true, "rateLimit": true },
   "templateApprovalSeconds": 5,
+  "numbers": { "limit": 5, "included": true, "trial": false, "metaConnect": false, "linksPerMinute": 10 },
+  "publicUrl": null,
   "subscriptions": [
     {
       "url": "http://localhost:3000/hooks/funnelchat",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelchat-hq/sandbox",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A local server that imitates the Funnelchat public API and sends signed webhooks, with no real effects",
   "license": "MIT",
   "author": {