@alaahedhly22/social-sim 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @alaahedhly22/social-sim
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Point an app's Meta and TikTok calls at [Social Sim](https://github.com/Hortensia-Agency/social-sim) with one env var, and drive the sim from tests. The app keeps its own Graph and TikTok code: the same paths, bodies, tokens and webhooks. Only the origin changes.
+
+| `SOCIAL_SIM_URL` | Where the calls go |
+|---|---|
+| unset (production) | `https://graph.facebook.com`, `https://open.tiktokapis.com`, … byte for byte as today |
+| `https://<your sim>` | the same paths under the sim: `https://<your sim>/graph.facebook.com/v22.0/me` |
+
+Never set `SOCIAL_SIM_URL` in production.
+
+## Install
+
+```
+pnpm add @alaahedhly22/social-sim
+```
+
+In a Claude Code session inside the app, `/integrate-social-sim` does the whole integration below.
+
+## Send the app's calls to the sim
+
+Pick one.
+
+**Build URLs from the origins (recommended).** One module in the app names the hosts; everything else imports from it:
+
+```ts
+// src/lib/platform-hosts.ts
+import { platformOrigins } from "@alaahedhly22/social-sim";
+
+export const { metaGraph, metaWww, tiktokApi, tiktokWww } = platformOrigins();
+// fetch(`${metaGraph}/v22.0/me/accounts?access_token=...`)
+// The login button: `${metaWww}/v22.0/dialog/oauth?client_id=...`
+```
+
+**Or wrap fetch,** for code or an SDK that writes `https://graph.facebook.com/...` itself. Call it once at startup (for Next.js, in `instrumentation.ts`); it does nothing when `SOCIAL_SIM_URL` is unset:
+
+```ts
+import { installSocialSim } from "@alaahedhly22/social-sim";
+installSocialSim();
+```
+
+`withSocialSim(fetch)` returns a wrapped fetch without touching the global, and `simUrl(url)` rewrites a single URL. Remember the browser: a login link the app renders must be built with `metaWww` / `tiktokWww` (or `simUrl`), since the fetch wrapper only sees server requests.
+
+Then, in the sim's console, register the app under **World → Apps** with the app's real id and secret and its webhook callback URL. The app's other env vars stay as they are.
+
+## Keep it that way
+
+A test in the app fails when a platform host is written anywhere but the host module:
+
+```ts
+import { findHardcodedHosts } from "@alaahedhly22/social-sim/testing";
+
+it("names Meta and TikTok hosts only in platform-hosts.ts", () => {
+  expect(findHardcodedHosts("src", { allow: ["src/lib/platform-hosts.ts"] })).toEqual([]);
+});
+```
+
+## Drive the sim from tests
+
+`SocialSim` runs the sim's director verbs, the same ones its MCP tools expose, typed by their inputs. It reads `SOCIAL_SIM_URL` and `SOCIAL_SIM_KEY` (the sim's `SIM_ACCESS_KEY`):
+
+```ts
+import { SocialSim } from "@alaahedhly22/social-sim/testing";
+
+const sim = new SocialSim();
+const { ids } = await sim.loadScenario("keyword-rule");
+await sim.verb("post_comment", { person: ids.customer_1, targetId: ids.media_1, text: "price?" });
+await sim.verb("wait_for_api_call", { method: "POST", path: `/${ids.page}/messages` });
+await sim.advanceClock("25h");
+```
+
+A refused verb throws `SocialSimError` with the sim's reason. `GET /api/director` on the sim lists every verb with its description.

package/dist/fetch.d.ts

@@ -0,0 +1,13 @@
+type Env = Record<string, string | undefined>;
+/**
+ * A fetch that sends Meta and TikTok requests to the sim when SOCIAL_SIM_URL
+ * is set, for code (or an SDK) that writes the platform URLs itself. Every
+ * other request, and every request with SOCIAL_SIM_URL unset, goes through untouched.
+ */
+export declare function withSocialSim(base?: typeof fetch, env?: Env): typeof fetch;
+/**
+ * Wraps the global fetch once at startup. Does nothing when SOCIAL_SIM_URL is
+ * unset, so it is safe to call in every environment, production included.
+ */
+export declare function installSocialSim(env?: Env): boolean;
+export {};

package/dist/fetch.js

@@ -0,0 +1,29 @@
+import { simBase, simUrl } from "./hosts.js";
+/**
+ * A fetch that sends Meta and TikTok requests to the sim when SOCIAL_SIM_URL
+ * is set, for code (or an SDK) that writes the platform URLs itself. Every
+ * other request, and every request with SOCIAL_SIM_URL unset, goes through untouched.
+ */
+export function withSocialSim(base = globalThis.fetch, env = process.env) {
+    if (!simBase(env))
+        return base;
+    return (input, init) => {
+        if (typeof input === "string" || input instanceof URL)
+            return base(simUrl(input, env), init);
+        const target = simUrl(input.url, env);
+        return base(target === input.url ? input : new Request(target, input), init);
+    };
+}
+const INSTALLED = Symbol.for("@alaahedhly22/social-sim/installed");
+/**
+ * Wraps the global fetch once at startup. Does nothing when SOCIAL_SIM_URL is
+ * unset, so it is safe to call in every environment, production included.
+ */
+export function installSocialSim(env = process.env) {
+    const global = globalThis;
+    if (global[INSTALLED] || !simBase(env))
+        return false;
+    global.fetch = withSocialSim(global.fetch.bind(globalThis), env);
+    global[INSTALLED] = true;
+    return true;
+}

package/dist/hosts.d.ts

@@ -0,0 +1,21 @@
+export declare const HOSTS: {
+    readonly metaGraph: "graph.facebook.com";
+    readonly metaWww: "www.facebook.com";
+    readonly metaRupload: "rupload.facebook.com";
+    readonly tiktokApi: "open.tiktokapis.com";
+    readonly tiktokUpload: "open-upload.tiktokapis.com";
+    readonly tiktokWww: "www.tiktok.com";
+};
+export type HostName = keyof typeof HOSTS;
+export type PlatformOrigins = Record<HostName, string>;
+type Env = Record<string, string | undefined>;
+/** The sim's origin from SOCIAL_SIM_URL, or null when the app talks to the real platforms. */
+export declare function simBase(env?: Env): string | null;
+/** Every platform origin, pointed at the sim when SOCIAL_SIM_URL is set. */
+export declare function platformOrigins(env?: Env): PlatformOrigins;
+/**
+ * Rewrites an absolute URL on one of the platform hosts to the sim; any other
+ * URL, or any URL with SOCIAL_SIM_URL unset, comes back unchanged.
+ */
+export declare function simUrl(url: string | URL, env?: Env): string;
+export {};

package/dist/hosts.js

@@ -0,0 +1,49 @@
+// The one place an app names Meta's and TikTok's hosts.
+//
+// Social Sim serves each platform host under a path named after it
+// (`${SOCIAL_SIM_URL}/graph.facebook.com/v22.0/me`), so everything past the
+// origin stays byte for byte the same. With SOCIAL_SIM_URL unset every origin
+// is the real one, so production never changes.
+export const HOSTS = {
+    metaGraph: "graph.facebook.com",
+    metaWww: "www.facebook.com",
+    metaRupload: "rupload.facebook.com",
+    tiktokApi: "open.tiktokapis.com",
+    tiktokUpload: "open-upload.tiktokapis.com",
+    tiktokWww: "www.tiktok.com",
+};
+/** The sim's origin from SOCIAL_SIM_URL, or null when the app talks to the real platforms. */
+export function simBase(env = process.env) {
+    const raw = env.SOCIAL_SIM_URL?.trim();
+    if (!raw)
+        return null;
+    if (!/^https?:\/\/[^/]+/.test(raw))
+        throw new Error(`SOCIAL_SIM_URL must be an http(s) origin, got "${raw}"`);
+    return raw.replace(/\/+$/, "");
+}
+/** Every platform origin, pointed at the sim when SOCIAL_SIM_URL is set. */
+export function platformOrigins(env = process.env) {
+    const base = simBase(env);
+    return Object.fromEntries(Object.entries(HOSTS).map(([name, host]) => [name, base ? `${base}/${host}` : `https://${host}`]));
+}
+const KNOWN = new Set(Object.values(HOSTS));
+/**
+ * Rewrites an absolute URL on one of the platform hosts to the sim; any other
+ * URL, or any URL with SOCIAL_SIM_URL unset, comes back unchanged.
+ */
+export function simUrl(url, env = process.env) {
+    const text = url.toString();
+    const base = simBase(env);
+    if (!base)
+        return text;
+    let parsed;
+    try {
+        parsed = new URL(text);
+    }
+    catch {
+        return text;
+    }
+    if (parsed.protocol !== "https:" || !KNOWN.has(parsed.hostname))
+        return text;
+    return `${base}/${parsed.hostname}${parsed.pathname}${parsed.search}${parsed.hash}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { HOSTS, platformOrigins, simBase, simUrl, type HostName, type PlatformOrigins } from "./hosts.js";
+export { installSocialSim, withSocialSim } from "./fetch.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { HOSTS, platformOrigins, simBase, simUrl } from "./hosts.js";
+export { installSocialSim, withSocialSim } from "./fetch.js";

package/dist/testing.d.ts

@@ -0,0 +1,41 @@
+import type { VerbInputs, VerbName } from "./verbs.js";
+export type { VerbInputs, VerbName } from "./verbs.js";
+type Env = Record<string, string | undefined>;
+export declare class SocialSimError extends Error {
+    readonly verb: string;
+    readonly status: number;
+    constructor(verb: string, status: number, message: string);
+}
+/**
+ * Drives a running sim from tests: the director's verbs (the same ones the MCP
+ * tools expose), typed by their inputs. `url` and `key` default to
+ * SOCIAL_SIM_URL and SOCIAL_SIM_KEY (the sim's SIM_ACCESS_KEY).
+ */
+export declare class SocialSim {
+    readonly url: string;
+    private readonly key;
+    constructor(options?: {
+        url?: string;
+        key?: string;
+        env?: Env;
+    });
+    /** Runs one verb and returns its result; a refusal throws SocialSimError with the sim's reason. */
+    verb<V extends VerbName>(name: V, ...input: Record<string, never> extends VerbInputs[V] ? [VerbInputs[V]?] : [VerbInputs[V]]): Promise<unknown>;
+    /** Loads a scenario and returns the ids it created (page, ig, customers, posts) and its plan. */
+    loadScenario(name: string): Promise<{
+        name: string;
+        ids: Record<string, string>;
+        plan: string[];
+    }>;
+    advanceClock(by: string): Promise<unknown>;
+    resetClock(): Promise<unknown>;
+}
+/** Every line under `dir` that names a platform host, skipping the files that may (the app's host module). */
+export declare function findHardcodedHosts(dir: string, options?: {
+    allow?: string[];
+    extensions?: string[];
+}): {
+    file: string;
+    line: number;
+    host: string;
+}[];

package/dist/testing.js

@@ -0,0 +1,79 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { HOSTS } from "./hosts.js";
+export class SocialSimError extends Error {
+    verb;
+    status;
+    constructor(verb, status, message) {
+        super(`${verb}: ${message}`);
+        this.verb = verb;
+        this.status = status;
+    }
+}
+/**
+ * Drives a running sim from tests: the director's verbs (the same ones the MCP
+ * tools expose), typed by their inputs. `url` and `key` default to
+ * SOCIAL_SIM_URL and SOCIAL_SIM_KEY (the sim's SIM_ACCESS_KEY).
+ */
+export class SocialSim {
+    url;
+    key;
+    constructor(options = {}) {
+        const env = options.env ?? process.env;
+        const url = options.url ?? env.SOCIAL_SIM_URL;
+        const key = options.key ?? env.SOCIAL_SIM_KEY;
+        if (!url)
+            throw new Error("SocialSim needs a url, or SOCIAL_SIM_URL set.");
+        if (!key)
+            throw new Error("SocialSim needs the sim's access key, or SOCIAL_SIM_KEY set.");
+        this.url = url.replace(/\/+$/, "");
+        this.key = key;
+    }
+    /** Runs one verb and returns its result; a refusal throws SocialSimError with the sim's reason. */
+    async verb(name, ...input) {
+        const res = await fetch(`${this.url}/api/director/${name}`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json" },
+            body: JSON.stringify(input[0] ?? {}),
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new SocialSimError(name, res.status, body.error ?? res.statusText);
+        return body.result;
+    }
+    /** Loads a scenario and returns the ids it created (page, ig, customers, posts) and its plan. */
+    async loadScenario(name) {
+        return (await this.verb("load_scenario", { name }));
+    }
+    advanceClock(by) {
+        return this.verb("advance_clock", { by });
+    }
+    resetClock() {
+        return this.verb("reset_clock");
+    }
+}
+/** Every line under `dir` that names a platform host, skipping the files that may (the app's host module). */
+export function findHardcodedHosts(dir, options = {}) {
+    const allow = new Set((options.allow ?? []).map((file) => path.resolve(file)));
+    const extensions = options.extensions ?? [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+    const hosts = Object.values(HOSTS);
+    const found = [];
+    const walk = (current) => {
+        for (const name of readdirSync(current)) {
+            if (name === "node_modules" || name.startsWith("."))
+                continue;
+            const full = path.join(current, name);
+            if (statSync(full).isDirectory())
+                walk(full);
+            else if (extensions.includes(path.extname(name)) && !allow.has(path.resolve(full)) && !/\.(test|spec)\.\w+$/.test(name)) {
+                readFileSync(full, "utf8").split("\n").forEach((text, index) => {
+                    for (const host of hosts)
+                        if (text.includes(host))
+                            found.push({ file: full, line: index + 1, host });
+                });
+            }
+        }
+    };
+    walk(dir);
+    return found;
+}

package/dist/verbs.d.ts

@@ -0,0 +1,547 @@
+export interface VerbInputs {
+    /** Start here: the clock, apps, people, Pages, creators, counts, delivery states, active faults and unmapped calls. */
+    describe_world: Record<string, never>;
+    /** The scenario packs, each a known starting world for a Sparkia feature, with the features it covers. */
+    list_scenarios: Record<string, never>;
+    /** Resets the world (apps and their settings stay) and builds a scenario. Returns the ids of everything it created and the test plan with those ids filled in. Sparkia has to connect again afterwards: its old tokens and ids are gone. */
+    load_scenario: {
+        name: string;
+    };
+    /** Empties the world and resets the clock, limits and Graph versions. Apps stay unless keepApps is false. */
+    reset_world: {
+        keepApps?: boolean;
+    };
+    /** Saves the whole world, apps and clock included, under a name (replacing a snapshot of that name). */
+    snapshot_world: {
+        name: string;
+    };
+    /** Replaces the world with a snapshot, clock included. Tokens Sparkia holds work again if they were in the snapshot. */
+    restore_snapshot: {
+        name: string;
+    };
+    /** Saved snapshots, newest first. */
+    list_snapshots: Record<string, never>;
+    /** Deletes a saved snapshot. */
+    delete_snapshot: {
+        name: string;
+    };
+    /** The sim time every window, expiry, schedule and retry reads, its offset from wall time, and whether it is frozen. */
+    get_clock: Record<string, never>;
+    /** Moves sim time forward (or back with a minus sign). Windows close, tokens and containers expire, and due webhooks and scheduled posts fire on the next tick, about a second later. */
+    advance_clock: {
+        /** A duration such as "25h", "90m", "7d", "1d12h", or milliseconds. */
+        by: string | number;
+    };
+    /** Sets sim time to an ISO 8601 instant. A frozen clock stays frozen at the new instant. */
+    set_clock: {
+        at: string;
+    };
+    /** Stops sim time where it is; nothing becomes due until it is advanced or resumed. */
+    freeze_clock: Record<string, never>;
+    /** Lets a frozen clock run again from the instant it shows. */
+    resume_clock: Record<string, never>;
+    /** Puts sim time back on wall time, running. */
+    reset_clock: Record<string, never>;
+    /** The Meta and TikTok apps in the sim with their mode, webhook setup and subscribed fields (secrets redacted). */
+    list_apps: Record<string, never>;
+    /** Registers an app. Give the app id (or client_key) and secret from Sparkia's env so Sparkia's calls authenticate; omit them to mint new ones. */
+    create_app: {
+        platform: "META" | "TIKTOK";
+        name: string;
+        appId?: string;
+        secret?: string;
+    };
+    /** Changes App Dashboard settings: mode (DEV or LIVE), app type (BUSINESS or CONSUMER), access level, audit status (TikTok), webhook callback (verified with the hub challenge before it is saved, like Meta does), subscribed fields as "object.field" (e.g. "instagram.comments", "page.feed"), and the other switches. */
+    configure_app: {
+        /** The app's sim id, Meta app id or TikTok client_key. */
+        app: string;
+        name?: string;
+        mode?: "DEV" | "LIVE";
+        /** Meta only. BUSINESS (the default): long-lived user tokens never expire. CONSUMER: they last 60 days. */
+        appType?: "BUSINESS" | "CONSUMER";
+        accessLevel?: "STANDARD" | "ADVANCED";
+        audited?: boolean;
+        requireAppSecretProof?: boolean;
+        includeValues?: boolean;
+        verifiedDomains?: string[];
+        subscribedFields?: string[];
+        callbackUrl?: string;
+        verifyToken?: string;
+        deauthorizeUrl?: string | null;
+        dataDeletionUrl?: string | null;
+    };
+    /** Runs the hub challenge against the app's saved callback URL, as the App Dashboard's Verify button does. */
+    verify_webhook: {
+        /** The app's sim id, Meta app id or TikTok client_key. */
+        app: string;
+    };
+    /** Every permission (TikTok: scope) the app's calls have needed since its history began, each with the endpoints that needed it, how many calls lacked it (Meta would refuse those), and the permissions its webhook subscriptions need. `reviewList` is what to request in App Review. Kept across scenario loads and resets. */
+    get_app_permissions: {
+        /** The app's sim id, Meta app id or TikTok client_key. */
+        app: string;
+    };
+    /** Forgets the app's permission history, so the next calls start a fresh list. */
+    clear_app_permissions: {
+        /** The app's sim id, Meta app id or TikTok client_key. */
+        app: string;
+    };
+    /** Queues the App Dashboard's sample event for a field, e.g. "instagram.comments". */
+    send_test_webhook: {
+        /** The app's sim id, Meta app id or TikTok client_key. */
+        app: string;
+        field: string;
+    };
+    /** Gives a person a role on an app (ADMIN, DEVELOPER, TESTER), which a Development-mode app requires before they can log in; null removes it. */
+    set_app_role: {
+        /** The app's sim id, Meta app id or TikTok client_key. */
+        app: string;
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        role: "ADMIN" | "DEVELOPER" | "TESTER" | null;
+    };
+    /** Sets a person's tasks on a Page (default: full admin, ADVERTISE, ANALYZE, CREATE_CONTENT, MESSAGING, MODERATE, MANAGE). Null removes the role, and their tokens for the Page answer 190/492 from then on. */
+    set_page_role: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        pageId: string;
+        tasks?: string[] | null;
+    };
+    /** Tokens the sim minted (Meta user, page and app tokens, TikTok access tokens) with their state; values are redacted. */
+    list_tokens: {
+        /** The app's sim id, Meta app id or TikTok client_key. */
+        app?: string;
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person?: string;
+    };
+    /** Makes a token expire now: a Meta token answers 190 (expired session); a TikTok access token answers access_token_invalid while its refresh token still works unless refresh is true. */
+    expire_token: {
+        id: string;
+        /** TikTok: expire the refresh token too. */
+        refresh?: boolean;
+    };
+    /** Makes a Meta token answer 190 with a subcode from now on: 458 app removed, 460 password changed, 463 expired, 467 invalid session, 492 page role lost. */
+    invalidate_token: {
+        id: string;
+        subcode: 458 | 460 | 463 | 467 | 492;
+    };
+    /** The person removes the app in their Facebook settings: their tokens answer 190/458 and the app's deauthorize callback is called. With deleteData, the data deletion callback is called too. */
+    remove_app_from_person: {
+        /** The app's sim id, Meta app id or TikTok client_key. */
+        app: string;
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        deleteData?: boolean;
+    };
+    /** Adds a person (a customer, or a Page admin who logs in through the dialog). Returns their sim id and Facebook user id. */
+    create_person: {
+        name: string;
+        email?: string;
+        phone?: string;
+        /** Needed to comment or DM on Instagram. */
+        igUsername?: string;
+        /** Facebook leaves `from` out of this person's comments. */
+        privateProfile?: boolean;
+        twoFactor?: boolean;
+        igFollowerCount?: number;
+        igVerified?: boolean;
+    };
+    /** Everyone in the world with their ids, Instagram handle, scoped ids and the Pages they manage. */
+    list_people: Record<string, never>;
+    /** Removes a person with their tokens, comments, likes and threads. */
+    delete_person: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+    };
+    /** Adds a Facebook Page, optionally with a linked Instagram professional account, and makes a person its admin. */
+    create_page: {
+        name: string;
+        username?: string;
+        category?: string;
+        fanCount?: number;
+        followersCount?: number;
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        admin?: string;
+        instagram?: {
+            username: string;
+            name?: string;
+            biography?: string;
+            followersCount?: number;
+            followsCount?: number;
+            /** API publishes per rolling 24 h; 100 by default. */
+            publishQuota?: number;
+            imageProcessingSec?: number;
+            videoProcessingSec?: number;
+        };
+    };
+    /** Pages with their linked Instagram accounts, admins and the apps subscribed to them. */
+    list_pages: Record<string, never>;
+    /** Removes a Page and its linked Instagram account with all their posts, media, comments and threads. Tokens for the Page stop working. */
+    delete_page: {
+        pageId: string;
+    };
+    /** A person follows or unfollows an Instagram account; Sparkia's follow gate reads this through is_user_follow_business. */
+    set_follow: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** The Instagram account id or username. */
+        instagram: string;
+        follows: boolean;
+    };
+    /** Whether Facebook shows who wrote this person's comments; hidden leaves `from` out of Graph reads, as Meta does for some profiles. */
+    set_from_visibility: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        visible: boolean;
+    };
+    /** The owner posts from the phone app (not through the API): a Facebook post (text, photo or video; emits the Page's feed webhook) or Instagram media (post, reel or story; no webhook, no quota). Gives customers something to comment on. */
+    create_post: {
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+        kind?: "post" | "reel" | "story";
+        /** The caption or message. */
+        text?: string;
+        /** A bundled sample (square.jpg, portrait.jpg, wide.jpg, square.png, short.mp4, landscape.mp4, story.mp4) or a URL the sim fetches. */
+        media?: {
+            fixture: "square.jpg" | "portrait.jpg" | "wide.jpg" | "square.png" | "short.mp4" | "landscape.mp4" | "story.mp4";
+        } | {
+            url: string;
+        };
+    };
+    /** The owner deletes a Facebook post or Instagram media in the app; Graph reads of it fail from then on, as after a delete on the platform. */
+    delete_post: {
+        id: string;
+    };
+    /** A business's posts or media, newest first, including what Sparkia published, with comment counts and whether each is live. */
+    list_posts: {
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+        limit?: number;
+    };
+    /** Turns comments on or off for an Instagram media, as the owner can in the app; comments on it are then refused. */
+    set_comments_enabled: {
+        mediaId: string;
+        enabled: boolean;
+    };
+    /** The owner hides, unhides or deletes a comment from the app. Emits what Meta sends for it (feed verb hide or remove on Facebook); deleting removes the replies too. */
+    moderate_comment: {
+        commentId: string;
+        action: "hide" | "unhide" | "delete";
+    };
+    /** A person comments on a Facebook post or Instagram media, or replies when targetId is a comment (a reply to a reply lands under the top comment, as both apps thread it). Emits the comments or feed webhook. */
+    post_comment: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** A Facebook post id, Instagram media id, or a comment id to reply to. */
+        targetId: string;
+        text: string;
+        /** Facebook only: a photo attached to the comment. */
+        photo?: {
+            fixture: "square.jpg" | "portrait.jpg" | "wide.jpg" | "square.png" | "short.mp4" | "landscape.mp4" | "story.mp4";
+        } | {
+            url: string;
+        };
+        /** Instagram only: the comment was left on an ad promoting this media. */
+        ad?: {
+            id: string;
+            title: string;
+        };
+    };
+    /** A person deletes a comment they wrote (and its replies go with it). */
+    delete_comment: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        commentId: string;
+    };
+    /** A person likes a Facebook post (emits a feed reaction webhook), an Instagram media or a comment. Liking twice changes nothing. */
+    like: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        targetId: string;
+    };
+    /** A person sends a direct message to a Page (Messenger) or an Instagram account. Opens or extends the 24 h window and emits the messages webhook. */
+    send_dm: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+        text?: string;
+        attachments?: ({
+            type: "image" | "video" | "audio" | "file";
+            url: string;
+        })[];
+        replyToMid?: string;
+    };
+    /** A person taps a quick reply or a postback button on a business message (the latest one by default), chosen by title, payload or position. A quick reply sends a message with its payload; a postback button sends messaging_postbacks; link and call buttons leave the thread and send nothing. */
+    tap_button: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+        /** The business message; defaults to the latest one. */
+        mid?: string;
+        title?: string;
+        payload?: string;
+        index?: number;
+        /** Generic template: which card the button is on. */
+        element?: number;
+    };
+    /** A person taps one of the ice breakers the business set with messenger_profile, by position (0 is the first). */
+    tap_ice_breaker: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+        index?: number;
+    };
+    /** A person taps an item in the business's persistent menu, by position (0 is the first). A postback item sends messaging_postbacks; a link item opens a page and sends nothing. */
+    tap_menu: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+        index?: number;
+    };
+    /** A person taps Get Started on a new Messenger thread with a Page. */
+    tap_get_started: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        pageId: string;
+    };
+    /** A person reacts to a message (the business's latest by default), or takes the reaction back with null. */
+    react_to_message: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+        mid?: string;
+        reaction?: "love" | "smile" | "wow" | "sad" | "angry" | "like" | null;
+    };
+    /** A person opens the thread and sees the business's latest message (emits the read or seen webhook; the window does not move). */
+    mark_seen: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+    };
+    /** A person edits one of their own messages. */
+    edit_message: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        mid: string;
+        text: string;
+    };
+    /** A person opens the thread from an m.me or ig.me link carrying a ref (emits the referral webhook). */
+    open_referral: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+        ref: string;
+    };
+    /** Calls Sparkia made to the sim's platform APIs, newest first, with request, response and status. */
+    list_api_calls: {
+        /** e.g. "graph.facebook.com" or "open.tiktokapis.com". */
+        host?: string;
+        method?: string;
+        /** A part of the request path, e.g. "/messages" or "/media_publish". */
+        path?: string;
+        status?: number;
+        /** Only calls logged after this API call id. */
+        afterId?: string;
+        limit?: number;
+    };
+    /** One API call with its full request and response. */
+    get_api_call: {
+        id: string;
+    };
+    /** Blocks until Sparkia makes a matching call logged after afterId (or after this tool was called) and returns it; returns {timedOut: true} otherwise. Use it to assert that Sparkia reacted, e.g. path "/messages" after posting a comment. Call it after the action, not alongside it (tool calls may run one at a time), and pass the action's apiCallCursor as afterId so a reply made before the wait began still counts. */
+    wait_for_api_call: {
+        /** e.g. "graph.facebook.com" or "open.tiktokapis.com". */
+        host?: string;
+        method?: string;
+        /** A part of the request path, e.g. "/messages" or "/media_publish". */
+        path?: string;
+        status?: number;
+        /** Match calls after this id (a customer action's apiCallCursor) instead of after now. */
+        afterId?: string;
+        timeoutMs?: number;
+    };
+    /** Webhook deliveries the sim sent or is sending to apps, newest first, with body, status and last attempt. */
+    list_webhook_deliveries: {
+        /** The sim id of the app. */
+        appId?: string;
+        object?: "page" | "instagram" | "tiktok";
+        status?: "PENDING" | "SENDING" | "RETRY_WAIT" | "DELIVERED" | "DEAD";
+        /** Text the delivered body contains, e.g. a comment id or "messaging_postbacks". */
+        contains?: string;
+        limit?: number;
+    };
+    /** Blocks until a matching delivery is created after this tool was called and returns it; returns {timedOut: true} otherwise. Add status DELIVERED to wait until the app accepted it. */
+    wait_for_webhook_delivery: {
+        /** The sim id of the app. */
+        appId?: string;
+        object?: "page" | "instagram" | "tiktok";
+        status?: "PENDING" | "SENDING" | "RETRY_WAIT" | "DELIVERED" | "DEAD";
+        /** Text the delivered body contains, e.g. a comment id or "messaging_postbacks". */
+        contains?: string;
+        timeoutMs?: number;
+    };
+    /** Sends a delivery's exact body again as a new delivery, the way the App Dashboard's resend does. */
+    redeliver_webhook: {
+        deliveryId: string;
+    };
+    /** Comments on a Facebook post or Instagram media with their replies, including hidden and deleted ones, as the business sees them. */
+    list_comments: {
+        /** A Facebook post id or Instagram media id. */
+        targetId: string;
+    };
+    /** The DM thread between a person and a business as the customer sees it, with what Sparkia sent (templates, quick replies, attachments) and whether the 24 h window is open. */
+    get_conversation: {
+        /** A person: the sim id, the Facebook user id, a PSID or IGSID, the Instagram username, or the exact name. */
+        person: string;
+        /** A business: a Page id or username, or an Instagram account id or username. */
+        business: string;
+    };
+    /** Changes a rate-limit ceiling. Kinds: app and user (Graph app and user buckets), pages, instagram and messenger (Business Use Case buckets), tiktok_post and tiktok_status. Lower one to trip throttling in a few calls. */
+    set_limit: {
+        kind: "app" | "user" | "pages" | "instagram" | "messenger" | "tiktok_post" | "tiktok_status";
+        ceiling?: number;
+        windowSec?: number;
+        timeCeilingMs?: number;
+    };
+    /** Every bucket's calls in its current window against its ceiling, as the usage headers report them. */
+    get_usage: Record<string, never>;
+    /** Sets a bucket's current window to a percentage of its ceiling without spending calls, e.g. 95 to make Sparkia back off. Buckets: "app:{metaAppId}", "user:{metaAppId}:{personSimId}", "buc:{pageId}:{pages|instagram|messenger}". */
+    set_usage: {
+        bucket: string;
+        percent: number;
+    };
+    /** Makes matching platform requests fail instead of reaching the handler: a platform error body (GRAPH_ERROR, also TikTok's envelope on TikTok hosts), a bare STATUS, Meta's HTML outage page, a DELAY, or a DROPped connection. First matching rule wins. */
+    add_fault: {
+        outcome: "GRAPH_ERROR" | "STATUS" | "HTML" | "DELAY" | "DROP";
+        /** Defaults to "graph.facebook.com". */
+        host?: string;
+        method?: string;
+        /** A regex on the path after the version, e.g. "oauth/access_token" or "messages$". */
+        pathPattern?: string;
+        /** Only requests made with this token (an id from list_tokens). */
+        tokenId?: string;
+        /** Matches before the rule is spent; omit for unlimited. */
+        count?: number;
+        /** Sim time the rule lives for; omit to keep it until cleared. */
+        ttl?: string | number;
+        status?: number;
+        error?: {
+            code: number;
+            subcode?: number;
+            type?: string;
+            message: string;
+        };
+        delayMs?: number;
+    };
+    /** Active fault rules in match order, with hits and matches left. */
+    list_faults: Record<string, never>;
+    /** Removes every fault rule. */
+    clear_faults: Record<string, never>;
+    /** How the sim delivers one app's webhooks: batch window, retry schedule ("meta" is Meta's real one, "compressed" retries within an hour), timeout, duplicate and reorder chances (0 to 1), and an added delay. */
+    set_webhook_policy: {
+        /** The app's sim id, Meta app id or TikTok client_key. */
+        app: string;
+        batchMs?: number;
+        schedule?: "meta" | "compressed" | number[];
+        timeoutMs?: number;
+        duplicateRate?: number;
+        reorderRate?: number;
+        delayMs?: number;
+    };
+    /** Sunsets a Graph API version at a sim instant (calls on it are served on the oldest live version from then, as Meta upgrades them), or makes it live again with null. */
+    set_version_sunset: {
+        version: string;
+        at: string | null;
+    };
+    /** Sets insight metric values (reach, likes, views, ...) on an Instagram media; metrics not named keep their value. */
+    set_media_insights: {
+        mediaId: string;
+        values: Record<string, number>;
+    };
+    /** Adds a TikTok creator someone can log in as on the Login Kit page. Private by default, since unaudited apps may only post to private accounts. */
+    tiktok_create_creator: {
+        displayName: string;
+        bio?: string;
+        /** Unaudited apps may only post to private accounts. */
+        isPrivate?: boolean;
+        isVerified?: boolean;
+        followerCount?: number;
+        followingCount?: number;
+        likesCount?: number;
+        commentDisabled?: boolean;
+        duetDisabled?: boolean;
+        stitchDisabled?: boolean;
+        maxVideoPostDurationSec?: number;
+        bannedFromPosting?: boolean;
+        dailyPostCap?: number;
+        /** Sim seconds a publish stays processing. */
+        processingSec?: number;
+        /** Sim seconds a public post waits before it is publicly available. */
+        moderationSec?: number;
+        username: string;
+    };
+    /** Changes a creator's account: privacy, posting ban and daily cap, duration limit, interaction switches, counts, and the processing and moderation delays. */
+    tiktok_set_creator: {
+        displayName?: string;
+        bio?: string;
+        /** Unaudited apps may only post to private accounts. */
+        isPrivate?: boolean;
+        isVerified?: boolean;
+        followerCount?: number;
+        followingCount?: number;
+        likesCount?: number;
+        commentDisabled?: boolean;
+        duetDisabled?: boolean;
+        stitchDisabled?: boolean;
+        maxVideoPostDurationSec?: number;
+        bannedFromPosting?: boolean;
+        dailyPostCap?: number;
+        /** Sim seconds a publish stays processing. */
+        processingSec?: number;
+        /** Sim seconds a public post waits before it is publicly available. */
+        moderationSec?: number;
+        /** A TikTok creator: the sim id, the username, or an open_id an app holds. */
+        creator: string;
+    };
+    /** Creators with the apps they authorized (open_id, scopes, removed or not) and their video counts. */
+    tiktok_list_creators: Record<string, never>;
+    /** The creator posts a video from the TikTok app (not through the API). A public one shows in video/list at once. */
+    tiktok_create_video: {
+        /** A TikTok creator: the sim id, the username, or an open_id an app holds. */
+        creator: string;
+        title?: string;
+        fixture?: "square.jpg" | "portrait.jpg" | "wide.jpg" | "square.png" | "short.mp4" | "landscape.mp4" | "story.mp4";
+        privacyLevel?: "PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY";
+    };
+    /** Content Posting API publishes with the status status/fetch would report now, the fail reason and the post id. */
+    tiktok_list_publishes: {
+        /** A TikTok creator: the sim id, the username, or an open_id an app holds. */
+        creator?: string;
+    };
+    /** Decides how a publish ends once its media is in (status no longer PROCESSING_UPLOAD with no bytes): fail it with a documented fail_reason, and/or change how long processing and moderation take from now. The post.publish webhooks follow. */
+    tiktok_set_publish_outcome: {
+        publishId: string;
+        /** Omit to let the publish complete. */
+        failReason?: "file_format_check_failed" | "duration_check_failed" | "frame_rate_check_failed" | "picture_size_check_failed" | "internal" | "video_pull_failed" | "photo_pull_failed" | "publish_cancelled" | "auth_removed" | "spam_risk_too_many_posts" | "spam_risk_user_banned_from_posting" | "spam_risk_text" | "spam_risk";
+        /** Processing ends this long from now. */
+        processing?: string | number;
+        /** A public post becomes publicly available this long after processing ends. */
+        moderation?: string | number;
+    };
+    /** Ends a creator's authorization of an app: tokens stop working, in-flight publishes fail with auth_removed, and the app is sent authorization.removed with the reason (0 unknown, 1 userDisconnect, 2 accountDeleted, 3 ageChanged, 4 accountBanned, 5 developerRevoke). */
+    tiktok_remove_authorization: {
+        openId?: string;
+        /** A TikTok creator: the sim id, the username, or an open_id an app holds. */
+        creator?: string;
+        /** With creator: the app's sim id or client_key. */
+        app?: string;
+        reason?: number;
+    };
+}
+export type VerbName = keyof VerbInputs;

package/dist/verbs.js

@@ -0,0 +1,2 @@
+// Generated from the sim's director verbs by `pnpm client:verbs`; do not edit.
+export {};

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@alaahedhly22/social-sim",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Point an app's Meta and TikTok calls at Social Sim with one env var, and drive the sim from tests.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Hortensia-Agency/social-sim.git",
+    "directory": "packages/client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "meta",
+    "facebook",
+    "instagram",
+    "tiktok",
+    "graph-api",
+    "testing",
+    "simulator"
+  ]
+}