@postact-js/sdk 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# @postact-js/sdk
+
+Typed client for the [postact](https://postact.app) API. One POST per action, zero dependencies.
+
+```sh
+npm i @postact-js/sdk
+```
+
+```ts
+import { createClient } from "@postact-js/sdk";
+
+// One client per project — create it once, at module scope.
+export const postact = createClient<{
+  signup: { plan: string };
+  "contact-form": { message: string };
+}>({
+  project: "acme",              // your project slug
+  key: process.env.POSTACT_SK!, // sk_… server key
+});
+
+// action + payload are checked against the map above
+const jobId = await postact.send("signup", { email: "ada@example.com" }, { plan: "pro" });
+```
+
+Untyped is fine too — `createClient({ … })` accepts any action slug and payload.
+
+## Person
+
+Every call needs a person with an email **or** at least one identifier:
+
+```ts
+await postact.send("signup", {
+  email: "ada@example.com",       // null clears it, omitted leaves it untouched
+  identifiers: { userId: 42 },    // your stable ids — used to merge, never duplicate
+  metadata: { plan: "pro" },      // stored on the person
+});
+```
+
+## Browser
+
+Use a `pk_…` key and add the origin to the action's allowlist in the dashboard. Never ship an
+`sk_…` key to a browser — it can read and write everything in the project.
+
+```ts
+const postact = createClient({ project: "acme", key: "pk_live_…" });
+```
+
+## Errors
+
+Non-2xx throws a `PostactError` carrying the server's message and `status` (401 bad key, 404
+unknown project/action, 429 rate limited, 400 invalid body). `send` resolves with a **job id** —
+the API is async, so a resolved promise means "queued", not "the action's steps ran".

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+export type Identifiers = Record<string, string | number>;
+export type Metadata = Record<string, string | number | boolean | null>;
+/** Who the action is about. Needs an email or at least one identifier. */
+export type Person = {
+    /** `null` clears the address, omitted leaves it untouched */
+    email?: string | null;
+    identifiers?: Identifiers;
+    metadata?: Metadata;
+};
+/** `{ "signup": { plan: string }, "contact-form": { message: string } }` */
+export type ActionMap = Record<string, Record<string, unknown> | undefined>;
+export type ClientOptions = {
+    /** project slug, e.g. `"acme"` */
+    project: string;
+    /** `sk_…` server key, or `pk_…` from a browser on an allowlisted origin */
+    key: string;
+    /** default `https://api.postact.app` */
+    baseUrl?: string;
+    /** override for tests / custom agents */
+    fetch?: typeof globalThis.fetch;
+};
+export declare class PostactError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function createClient<A extends ActionMap = ActionMap>(options: ClientOptions): {
+    /**
+     * Fire one action. Resolves with the queued job id — the API is async (202 + job),
+     * so this returning does not mean the action's steps have run.
+     */
+    send<K extends keyof A & string>(action: K, person: Person, payload?: A[K]): Promise<string>;
+};
+export type PostactClient<A extends ActionMap = ActionMap> = ReturnType<typeof createClient<A>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAC1D,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;AAExE,0EAA0E;AAC1E,MAAM,MAAM,MAAM,GAAG;IACnB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;AAE5E,MAAM,MAAM,aAAa,GAAG;IAC1B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC,CAAC;AAEF,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,OAAO,EAAE,aAAa;IAOhF;;;OAGG;SACQ,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,UAC3B,CAAC,UACD,MAAM,YACJ,CAAC,CAAC,CAAC,CAAC,GACb,OAAO,CAAC,MAAM,CAAC;EAmBrB;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,IAAI,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/index.js

@@ -0,0 +1,38 @@
+// Zero-dependency client for the postact one-POST API:
+//   POST {baseUrl}/p/<project>/a/<action>   { person, payload }
+// Typing comes from a caller-supplied action→payload map — no codegen, no generated schema to
+// drift; the map *is* the contract. Works anywhere `fetch` exists (Node 18+, Bun, browsers, edge).
+export class PostactError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "PostactError";
+        this.status = status;
+    }
+}
+export function createClient(options) {
+    const base = (options.baseUrl ?? "https://api.postact.app").replace(/\/+$/, "");
+    const project = encodeURIComponent(options.project);
+    // bind: an unbound globalThis.fetch throws "Illegal invocation" in browsers
+    const call = options.fetch ?? globalThis.fetch.bind(globalThis);
+    return {
+        /**
+         * Fire one action. Resolves with the queued job id — the API is async (202 + job),
+         * so this returning does not mean the action's steps have run.
+         */
+        async send(action, person, payload) {
+            // The server enforces this too; checking here saves a round trip for the common typo.
+            if (person.email === undefined && !Object.keys(person.identifiers ?? {}).length)
+                throw new PostactError("person needs an email or at least one identifier", 400);
+            const res = await call(`${base}/p/${project}/a/${encodeURIComponent(action)}`, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${options.key}` },
+                body: JSON.stringify({ person, payload }),
+            });
+            const body = (await res.json().catch(() => null));
+            if (!res.ok || !body?.job)
+                throw new PostactError(body?.error ?? `request failed (${res.status})`, res.status);
+            return body.job;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@postact-js/sdk",
+  "version": "0.1.0",
+  "description": "Typed client for the postact API — one POST per action.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "homepage": "https://postact.app",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^5"
+  }
+}