@funnelchat-hq/sandbox 0.1.1 → 0.3.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-KH6A3I2A.js';
+import { ConfigError, parseArgs, VERSION, DEFAULT_PORT, DEFAULT_CONFIG_FILE, resolveConfig, createSandbox } from './chunk-PCGMUC35.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,8 @@ 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).
+      --no-group-actions         Turn off the send to a group by API (on 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

@@ -10,6 +10,12 @@ interface PresetSubscription {
     /** Optional: a fixed id (UUID). */
     id?: string;
 }
+/** A workspace created at start (and after every reset) besides the default one, with fixed keys. */
+interface PresetWorkspace {
+    name: string;
+    /** Keys of that workspace (`<id>|fc_live_<letters and digits>`). Any other key belongs to the default workspace. */
+    keys: string[];
+}
 interface SandboxConfig {
     port: number;
     host: string;
@@ -39,8 +45,40 @@ interface SandboxConfig {
     };
     /** Seconds until a template created through the API goes from `PENDING` to `APPROVED`. `null`: it stays pending. */
     templateApprovalSeconds: number | null;
-    /** Subscriptions to create at start and after every reset. */
+    /** Subscriptions to create at start and after every reset, in the default workspace. */
     subscriptions: PresetSubscription[];
+    /** Workspaces to create at start and after every reset, besides the default one (ids 2, 3… in this order). */
+    workspaces: PresetWorkspace[];
+    /**
+     * 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;
+    };
+    /**
+     * The group actions by API (`POST /groups/{group}/messages`, `GET /groups/actions/{action}`). `true` (the default,
+     * like production, where communities' kill switch `API_GROUP_ACTIONS_ENABLED` is on). `false` imitates the switch
+     * off: every key gets `403 route_not_available`.
+     */
+    groupActions: boolean;
+    /**
+     * 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,21 +98,84 @@ interface MessageError {
     reason: string | null;
 }
 type DeviceKind = 'cloud' | 'qr';
+/** The aggregated health of an official number (accounts `MetaHealthStatusService`). */
+type HealthState = 'available' | 'limited' | 'blocked' | 'unknown';
+/**
+ * A workspace of the account (accounts `workspaces`). Every API key belongs to one and only sees and creates there
+ * (accounts v1.5.97, workspaces-api-keys). What has no workspace (`null`) counts as the default one's.
+ */
+interface Workspace {
+    id: number;
+    name: string;
+    isDefault: boolean;
+    createdAt: Date;
+}
 interface Device {
     id: number;
+    /** The workspace the number is in; `null` counts as the default one. */
+    workspaceId: number | null;
     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;
+    /** The workspace of the key that created it: the number it creates lands there. */
+    workspaceId: number | null;
+    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;
+    /** The workspace the contact is in; `null` counts as the default one. */
+    workspaceId: number | null;
     name: string | null;
     email: string | null;
     /** Digits only: the API stores the phone without `+`. */
@@ -136,9 +237,51 @@ interface CustomField {
     createdAt: Date;
     updatedAt: Date;
 }
+/** A participant of a group: the phone in digits, and whether it is an admin. */
+interface GroupParticipant {
+    phone: string;
+    name: string | null;
+    admin: boolean;
+}
+/** A WhatsApp group of a number of the account (communities `groups`). */
+interface Group {
+    id: number;
+    /** The WhatsApp id of the group, `120363…@g.us`: the `{group}` of the routes and `group.uid` of the events. */
+    uid: string;
+    name: string;
+    description: string;
+    /** The number that is in the group (a QR number: the sandbox account has no official groups). */
+    deviceId: number;
+    /** The workspace the group is in; `null` counts as the default one. */
+    workspaceId: number | null;
+    participants: GroupParticipant[];
+    link: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** `queued` → `running` → `completed` | `failed` (communities `ApiGroupAction::publicStatus()`). */
+type GroupActionStatus = 'queued' | 'running' | 'completed' | 'failed';
+/** A group action by API (communities `api_group_actions`): here, only `send_message`. */
+interface GroupAction {
+    uuid: string;
+    type: 'send_message';
+    status: GroupActionStatus;
+    deviceId: number;
+    groupId: number;
+    /** The workspace of the key that called (`call_context.workspace_id`). */
+    workspaceId: number;
+    result: Record<string, unknown> | null;
+    reason: string | null;
+    createdAt: Date;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    failedAt: Date | null;
+}
 type TemplateStatus = 'PENDING' | 'APPROVED' | 'REJECTED' | 'PAUSED' | 'DISABLED';
 interface Template {
     id: number;
+    /** The workspace it belongs to; `null` counts as the default one. */
+    workspaceId: number | null;
     uid: string;
     name: string;
     body: string;
@@ -164,6 +307,8 @@ interface Template {
 type SubscriptionStatus = 'active' | 'paused' | 'disabled';
 interface Subscription {
     id: string;
+    /** The workspace it belongs to: it only gets that workspace's events. `null` counts as the default one. */
+    workspaceId: number | null;
     url: string;
     description: string | null;
     events: string[];
@@ -251,6 +396,18 @@ interface RequestLogEntry {
     requestBody: unknown;
     responseBody: unknown;
 }
+/** An event the sandbox emitted, delivered or not: the panel shows them, so a status is seen without a receiver. */
+interface EmittedEvent {
+    envelope: {
+        id: string;
+        type: string;
+        version: number;
+        occurred_at: string;
+        data: unknown;
+    };
+    /** How many subscriptions got it. */
+    subscriptions: number;
+}
 /** A failure armed with `POST /_sandbox/failures` or the `X-Sandbox-*` headers. */
 interface ArmedFailure {
     id: number;
@@ -274,6 +431,9 @@ declare class Sequence {
 }
 declare class Store {
     readonly historyLimit: number;
+    workspaces: Map<number, Workspace>;
+    /** The sandbox keys minted for a workspace (`POST /_sandbox/workspaces`, `/_sandbox/keys`): any other key is the default one's. */
+    keys: Map<string, number>;
     devices: Map<number, Device>;
     contacts: Map<number, Contact>;
     messages: Map<number, Message>;
@@ -283,10 +443,26 @@ declare class Store {
     subscriptions: Map<string, Subscription>;
     deliveries: Delivery[];
     requests: RequestLogEntry[];
+    events: EmittedEvent[];
     failures: ArmedFailure[];
     forms: Map<number, FormVersion>;
     formFamilies: Map<number, FormFamily>;
     formRuns: Map<number, FormRun>;
+    connectLinks: Map<number, ConnectLink>;
+    groups: Map<number, Group>;
+    groupActions: Map<string, GroupAction>;
+    /** 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. */
@@ -305,6 +481,8 @@ declare class Store {
     /** Salt of the deterministic event ids: new on every reset, so ids never repeat across sessions. */
     eventSalt: string;
     readonly ids: {
+        workspace: Sequence;
+        apiKey: Sequence;
         contact: Sequence;
         message: Sequence;
         tag: Sequence;
@@ -317,9 +495,15 @@ declare class Store {
         formFamily: Sequence;
         formVersion: Sequence;
         formRun: Sequence;
+        device: Sequence;
+        connectLink: Sequence;
+        group: Sequence;
     };
     constructor(historyLimit?: number);
+    /** The default workspace of the account: where what has no workspace belongs. */
+    get defaultWorkspace(): Workspace;
     logRequest(entry: Omit<RequestLogEntry, 'id'>): RequestLogEntry;
+    logEvent(entry: EmittedEvent): void;
     addDelivery(entry: Omit<Delivery, 'id'>): Delivery;
     findContactByPhone(phone: string): Contact | undefined;
     contactMessages(contactId: number): Message[];
@@ -339,12 +523,20 @@ declare class Store {
  *   `429` is retried, any other answer that is not `2xx` is final;
  * - a delivery that runs out of attempts counts one consecutive failure; at 5 the subscription is disabled
  *   (`too_many_failures`); a success resets the count;
- * - each attempt checks again that the subscription exists, is `active` and still wants the type.
+ * - each attempt checks again that the subscription exists, is `active` and still wants the type;
+ * - an event reaches only the subscriptions of its workspace, and `data.workspace_id` says which one (accounts
+ *   v1.5.97 `EventWorkspaceRouting`, Q35 of 04-11): the workspace the emitter declares when it is one of the account,
+ *   the default one otherwise. A subscription without a workspace counts as the default one's.
  */
 
 interface EmitOptions {
     id?: string;
     occurredAt?: Date;
+    /**
+     * The workspace the event belongs to: the number's for `device.*`, the contact's or the group's for the rest.
+     * Missing, `null` or not a workspace of the account: the default one.
+     */
+    workspaceId?: number | null;
 }
 interface Envelope$1 {
     id: string;
@@ -365,7 +557,10 @@ declare class Webhooks {
     get maxAttempts(): number;
     /** Builds the envelope, exactly as it is delivered. */
     envelope(type: string, data: unknown, options?: EmitOptions): Envelope$1;
-    /** Emits one event to every active subscription that wants it. Returns the envelope and how many got it. */
+    /**
+     * Emits one event to every active subscription of its workspace that wants it. Returns the envelope and how many
+     * got it.
+     */
     emit(type: string, data: unknown, options?: EmitOptions): {
         envelope: Envelope$1;
         subscriptions: number;
@@ -374,7 +569,10 @@ declare class Webhooks {
     send(subscription: Subscription, type: string, body: string): Promise<SendResult>;
     private shouldRetry;
     private attempt;
-    /** `POST /api/v1/webhooks/{id}/test`: one synchronous `webhook.test`, no retries, no counters touched. */
+    /**
+     * `POST /api/v1/webhooks/{id}/test`: one synchronous `webhook.test`, no retries, no counters touched. Its
+     * `data.workspace_id` is the subscription's workspace.
+     */
     test(subscription: Subscription): Promise<Record<string, unknown>>;
 }
 
@@ -398,7 +596,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;
@@ -487,4 +689,4 @@ declare const FORM_TEMPLATES: FormTemplate[];
 
 declare const VERSION: string;
 
-export { type CatalogEntry, type ConfigInput, type CreateSandboxOptions, DELIVERY_HEADER, EDGE_ERRORS, EVENT_HEADER, FAILURE_REASONS, FORM_TEMPLATES, META_ERRORS, type PresetSubscription, REJECTIONS, REQUEST_ID_HEADER, SEND_FILE_TYPES, SIGNATURE_HEADER, SUPPORTED_EXTENSIONS, type Sandbox, type SandboxConfig, VERSION, catalog, createSandbox, defaultConfig, mergeConfig, signature };
+export { type CatalogEntry, type ConfigInput, type CreateSandboxOptions, DELIVERY_HEADER, EDGE_ERRORS, EVENT_HEADER, FAILURE_REASONS, FORM_TEMPLATES, META_ERRORS, type PresetSubscription, type PresetWorkspace, REJECTIONS, REQUEST_ID_HEADER, SEND_FILE_TYPES, SIGNATURE_HEADER, SUPPORTED_EXTENSIONS, type Sandbox, type SandboxConfig, VERSION, catalog, createSandbox, defaultConfig, mergeConfig, signature };

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-KH6A3I2A.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-PCGMUC35.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/funnelchat-sandbox.config.example.json

@@ -4,6 +4,10 @@
   "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 },
+  "groupActions": true,
+  "publicUrl": null,
+  "workspaces": [{ "name": "Cliente B", "keys": ["2|fc_live_clienteB"] }],
   "subscriptions": [
     {
       "url": "http://localhost:3000/hooks/funnelchat",

package/package.json

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

package/spec/procedencia.json

@@ -2,63 +2,67 @@
   "description": "Where each file of spec/ came from. Written by `npm run generate -- --spec <file>` or `-- --pending <file>`; do not edit it by hand. spec/pending-sandbox.json belongs to this repo: its sources are inside it.",
   "snapshot": {
     "file": "spec/funnelchat.json",
-    "sha256": "8bbbae569b4cab520884db98f28204156c1bd6c629578bee609343c193e0dadb",
-    "bytes": 635293,
+    "sha256": "0f451feaba59418f3a556f58856f841f12570973fd6525103e8cc0128ab64374",
+    "bytes": 1168453,
     "source": {
       "repository": "git@github.com:Funnelchat20/developers-portal.git",
-      "path": "out/specs/funnelchat.json",
-      "branch": "feat/openapi-unificada",
-      "commit": "0ef4abb008870ed8c7cae49a08900a81e5e57ed8",
-      "commit_date": "2026-10-15T10:53:11-03:00",
+      "path": "generated/specs/funnelchat-completa.json",
+      "branch": "main",
+      "commit": "c90565e4f1aa",
+      "commit_date": null,
       "file_tracked_in_git": false,
-      "tracked_files_clean": true,
-      "file_modified_at": "2026-10-15T14:11:20.569Z"
+      "tracked_files_clean": null,
+      "file_modified_at": "2026-11-04T21:06:16.945Z",
+      "note": "Built by `npm run build` of developers-portal at the merge of PR #33, deployed as v0.6.0 on 04-11. Not the published /specs/ file, which carries only the 23 visible operations."
     },
-    "imported_at": "2026-10-16T11:46:40.094Z",
+    "imported_at": "2026-11-04T21:13:28.643Z",
     "spec": {
       "openapi": "3.1.0",
       "title": "Funnelchat API",
       "version": "v0",
-      "paths": 191,
-      "operations": 230,
-      "webhooks": 28,
+      "paths": 203,
+      "operations": 248,
+      "webhooks": 29,
       "domains": [
         {
           "domain": "conversations",
-          "sha": "9d723d52c",
-          "branch": "snapshot/referencia-1310",
-          "snapshot_at": "2026-10-13T10:41:30-03:00"
+          "tag": "v1.19.7",
+          "sha": "4e35ddb83",
+          "branch": null,
+          "snapshot_at": null
         },
         {
           "domain": "communities",
-          "sha": "fab0bb10",
-          "branch": "snapshot/referencia-1310",
-          "snapshot_at": "2026-10-13T10:41:34-03:00"
+          "tag": "v2.35.5",
+          "sha": "2be913d4",
+          "branch": null,
+          "snapshot_at": null
         },
         {
           "domain": "accounts",
-          "sha": "c234b6f8",
-          "branch": "snapshot/referencia-1310",
-          "snapshot_at": "2026-10-13T10:41:36-03:00"
+          "tag": "v1.5.97",
+          "sha": "558332bcf",
+          "branch": null,
+          "snapshot_at": null
         }
       ]
     }
   },
   "pending": {
     "file": "spec/pending.json",
-    "sha256": "a14bc4dbc3025d3e958ffda8afd1fa9fdab34af264418060825f3300799aceb0",
-    "bytes": 32775,
+    "sha256": "3ccf04ff5aa2b6acf6baa9b3d7e56ba1fee1e9c83ae1906b16cedb8422da942a",
+    "bytes": 116917,
     "source": {
       "repository": "git@github.com:Funnelchat20/funnelchat-node.git",
       "path": "spec/pending.json",
-      "branch": "feat/inicial",
-      "commit": "88557ce7819c5a4061e84c58053a1b6c49f35ec2",
-      "commit_date": "2026-10-16T02:46:14-03:00",
+      "branch": "feat/primer-uso",
+      "commit": "8469a5c176ef36506b0102a68e2c506d0ff21407",
+      "commit_date": "2026-11-04T18:19:31-03:00",
       "file_tracked_in_git": true,
       "tracked_files_clean": true,
-      "file_modified_at": "2026-10-16T05:29:09.348Z"
+      "file_modified_at": "2026-11-04T21:15:57.746Z"
     },
-    "imported_at": "2026-10-16T11:46:40.294Z",
+    "imported_at": "2026-11-04T21:53:13.074Z",
     "note": "The pending layer of the Node SDK, unchanged. What belongs to the sandbox goes in spec/pending-sandbox.json."
   }
 }