@productcraft/social 1.0.3 → 1.1.0

package/README.md

@@ -1,229 +1,241 @@
 # @productcraft/social
 
-Typed Node.js SDK for [ProductCraft Social](https://productcraft.co) — social-as-a-service backend: communities, posts, ranked feeds, stories (with polls + close-friends), direct conversations, notifications, moderation, flags. Generic actor / object / edge primitives.
+Node.js / TypeScript client for **ProductCraft Social**: communities, actors, posts and comments, ranked feeds, stories, the follow graph, direct conversations, notifications and moderation.
 
-```bash
-npm install @productcraft/social
-```
-
-Server-side only. Customer-facing apps integrate via a backend (BFF pattern) that holds the workspace PAK (`pcft_live_…`).
+Every method, type, error class and mock is generated from the production OpenAPI spec. Coming from 1.0's raw `social.client.POST("/v1/…")` calls? `.client` still works unchanged; the [1.1 migration guide](https://github.com/clauderanelagh/productcraft-node/blob/main/docs/migrations/social-1.1.0.md) shows the resource method for every call shape.
 
-## Two caller contexts
+## Install
 
-Social's surface splits two ways — both reach the same data but differ in auth + URL shape:
-
-| Caller | URL prefix | Auth | What you do |
-|---|---|---|---|
-| **PlatformUser admin** | `/v1/workspaces/{workspace_id}/...` | cookie or PAK | Create communities, run moderation, read analytics. |
-| **Customer backend** | `/v1/communities/{community_id}/...` | PAK + `X-Acting-As: <actor_id>` header | Day-to-day reads/writes on behalf of an EndUser. |
+```sh
+npm install @productcraft/social
+```
 
-The customer backend acts on behalf of one of its EndUsers via the `X-Acting-As` header — the SDK passes whatever you put in headers straight through, so a per-request wrapper that injects the acting actor id is idiomatic.
+Node 20.3 or later, Bun, Deno and edge runtimes. Server-side only: your backend holds the workspace key (`pcft_live_…`) and calls Social on behalf of your users. Or install the umbrella package for every product: `npm install productcraft`.
 
-## Quick start — create a community (admin)
+## Quick start
 
-```ts before
+```ts
 import { Social } from "@productcraft/social";
 
-// Reads PRODUCTCRAFT_API_KEY from the environment
+// Reads PRODUCTCRAFT_API_KEY from the environment.
 const social = new Social();
 
-const { data, error } = await social.client.POST(
-  "/v1/workspaces/{workspace_id}/communities",
-  {
-    params: { path: { workspace_id: "<workspace-uuid>" } },
-    body: { display_name: "Founders Club", slug: "founders" },
-  },
-);
-```
+// Workspace-level: communities themselves (the workspace id is resolved from the key, or pass workspaceId).
+const { id: communityId } = await social.communities.create({ display_name: "Founders Club", slug: "founders" });
+
+// Community-level: bind the community once, then act as one of its actors.
+const community = social.community(communityId);
+const { actor } = await community.actors.create({ external_id: "user_123", display_name: "Ada" }); // upsert by your user id
+const c = community.as(actor.id); // fills actor_id in every body or query that declares it
 
-## Quick start — post on behalf of an EndUser (customer backend)
-
-```ts before
-const actor_id = "<actor-uuid>"; // the EndUser's Social actor id
-
-const { data, error } = await social.client.POST(
-  "/v1/communities/{community_id}/posts",
-  {
-    params: {
-      path: { community_id: "<community-uuid>" },
-      header: { "X-Acting-As": actor_id },
-    },
-    body: {
-      // `actor_id` is required in the body too — the header sets caller
-      // identity; the body field is the author of the post (typically
-      // the same UUID, but allowed to differ on admin-impersonation flows).
-      actor_id,
-      text: "Hello, world!",
-      visibility: "public",
-    },
-  },
-);
+const post = await c.posts.create({ body: "Hello from the SDK" });
+await c.posts.comments.create(post.id, { body: "First!" });
+for await (const item of c.actors.feed.list(actor.id, { limit: 50 })) console.log(item);
 ```
 
-Social's wire is snake_case both at the DTO level and in TS types — there's no name translation layer for this surface. Use snake_case keys in `body` to match what the API actually accepts.
+## Two levels: workspace and community
 
-## Migrating from 0.x to 1.0
+| Calls on | Reach them through | Typical caller |
+|---|---|---|
+| Communities (create, list, analytics), moderation, workspace webhooks, stats | `social.communities.*`, `social.webhooks.*`, `social.stats` | Your admin tooling |
+| Everything inside one community: actors, posts, comments, feeds, follows, conversations, notifications, community webhooks | `social.community(communityId).…` | Your product backend, per request |
 
-1.0 renames every **path parameter** to snake_case, to match the rest of the ProductCraft APIs: `{communityId}` is now `{community_id}`, `{actorId}` is `{actor_id}`, `{srcActorId}` is `{src_actor_id}`, and so on. Request URLs are unchanged, so nothing breaks at runtime; the change is in the TypeScript path keys and in `params.path`:
+`.as(actorId)` returns a copy of the community scope that fills `actor_id` (the acting user) wherever the API declares it. A call that passes its own `actor_id` wins:
 
-```ts before
-// 0.x
-await social.client.GET("/v1/communities/{communityId}/posts/{postId}", {
-  params: { path: { communityId, postId } },
-});
+```ts
+import { Social } from "@productcraft/social";
+declare const communityId: string, adaId: string, graceId: string, postId: string;
+const social = new Social();
 
-// 1.0
-await social.client.GET("/v1/communities/{community_id}/posts/{post_id}", {
-  params: { path: { community_id: communityId, post_id: postId } },
-});
+const asAda = social.community(communityId).as(adaId);
+await asAda.follows.create({ dst_actor_id: graceId });                 // actor_id: adaId
+await asAda.posts.reactions.create(postId, { type: "like", actor_id: graceId }); // explicit wins
+const unread = await asAda.actors.notifications.unreadCount(adaId);
+const dm = await asAda.conversations.create({ kind: "direct", recipient_actor_id: graceId });
+await asAda.conversations.messages.create(dm.id, { body: "Hi Grace" });
 ```
 
-Where a route names a target actor next to the acting `actor_id`, the target got its own name: `posts/{post_id}/tags/{tagged_actor_id}/approve`, `actors/{tagged_actor_id}/tagged`, `actors/{owner_actor_id}/highlights`, `lists/{list_id}/members/{member_actor_id}`, `conversations/{conversation_id}/members/{member_actor_id}`. A search-and-replace of the placeholders plus the `path` keys is the whole migration. Post `attributes` now read back with the keys exactly as you stored them (`imageUrl` stays `imageUrl`); before, the API returned them snake_cased.
+Social's wire is snake_case and so are the request and response types: no re-casing. Positional arguments (`postId`, `actorId`) and client options are camelCase.
+
+## Credentials
+
+| Credential | Pass | Use it for |
+|---|---|---|
+| Workspace API key (`pcft_live_…`) | `apiKey`, or `PRODUCTCRAFT_API_KEY` in the environment | Your backend, for everything |
+| Platform session (a signed-in person) | `auth: { type: "bearer", token }` plus `workspaceId` | Admin tooling acting as a console user |
+
+An explicit `apiKey` or `auth` always wins over the environment. The environment fallback is server-only: never put a key in `NEXT_PUBLIC_*` or any variable a bundler inlines into browser code. A keyed client constructed in a browser throws unless you set `dangerouslyAllowBrowser: true`.
+
+<!-- generated:start (scripts/gen-sdk.mjs; edits between the markers are overwritten) -->
+
+## Resources
+
+Full reference: [api.md](./api.md).
+
+- `social.communities`: `actors.comments.list`, `actors.reactions.list`, `analytics`, `create`, `delete`, `list`, `moderation.actions.create`, `moderation.actors.shadowBan`, `moderation.actors.unshadowBan`, `moderation.audit.list`, `moderation.blockedTerms.create`, `moderation.blockedTerms.delete`, `moderation.blockedTerms.list`, `moderation.conversations.list`, `moderation.conversations.messages.list`, `moderation.flags.list`, `moderation.flags.resolve`, `moderation.shadowBanned.list`, `retrieve`, `update`, `webhooks.endpoints.create`, `webhooks.endpoints.delete`, `webhooks.endpoints.list`, `webhooks.endpoints.retrieve`, `webhooks.endpoints.rotateSecret`, `webhooks.endpoints.test`, `webhooks.endpoints.update`, `webhooks.eventTypes.list`, `webhooks.events.list`, `webhooks.events.replay`, `webhooks.events.retrieve`
+- `social.community(…).actors`: `archived.list`, `assets.list`, `batch`, `blocks.list`, `bookmarks.list`, `byExternal.batch`, `byExternal.retrieve`, `closeFriends.list`, `counters`, `create`, `delete`, `dismissedSuggestions.list`, `drafts.list`, `feed.list`, `followRequests.list`, `followers.list`, `following.list`, `hashtagFollows.create`, `hashtagFollows.delete`, `hashtagFollows.list`, `hides.list`, `highlights.list`, `insights`, `list`, `mentions.list`, `mutedTerms.create`, `mutedTerms.delete`, `mutedTerms.list`, `mutes.list`, `notificationPrefs.list`, `notificationPrefs.update`, `notifications.list`, `notifications.markAllRead`, `notifications.unreadCount`, `notifications.update`, `postState`, `relationships.list`, `restricts.list`, `retrieve`, `scheduledPosts.list`, `storyTray.list`, `suggestedFollows.list`, `tagged.list`, `update`
+- `social.community(…).assets`: `complete`, `create`, `delete`, `retrieve`
+- `social.community(…).blocks`: `create`, `delete`
+- `social.community(…).closeFriends`: `create`, `delete`
+- `social.community(…).collections`: `create`, `delete`, `items.create`, `items.delete`, `items.list`, `items.update`, `list`, `retrieve`, `update`
+- `social.community(…).connections`: `accept`, `create`, `delete`
+- `social.community(…).conversations`: `create`, `delete`, `list`, `markRead`, `members.create`, `members.delete`, `members.update`, `messages.create`, `messages.delete`, `messages.list`, `messages.reactions.create`, `messages.reactions.delete`, `messages.reactions.list`, `messages.retrieve`, `messages.update`, `retrieve`, `unreadCount`, `update`
+- `social.community(…).counters`: `list`
+- `social.community(…).discoverFeed`: `list`
+- `social.community(…).dismissedSuggestions`: `create`, `delete`
+- `social.community(…).flags`: `create`, `list`
+- `social.community(…).followRequests`: `approve`, `delete`
+- `social.community(…).follows`: `batch`, `create`, `delete`
+- `social.community(…).hashtags`: `list`, `posts.list`, `retrieve`
+- `social.community(…).hides`: `create`, `delete`
+- `social.community(…).lists`: `create`, `delete`, `feed.list`, `list`, `members.create`, `members.delete`, `members.list`, `retrieve`, `update`
+- `social.community(…).mutes`: `create`, `delete`
+- `social.community(…).posts`: `bookmark`, `comments.approve`, `comments.create`, `comments.delete`, `comments.list`, `comments.pin`, `comments.reactions.create`, `comments.reactions.delete`, `comments.reactions.list`, `comments.retrieve`, `comments.unpin`, `comments.update`, `create`, `delete`, `insights`, `list`, `pollResults`, `quotes.list`, `reactions.create`, `reactions.delete`, `reactions.list`, `recordImpressions`, `recordView`, `repost`, `reposts.list`, `retrieve`, `revisions.list`, `tags.approve`, `tags.delete`, `unbookmark`, `unrepost`, `update`, `viewers.list`, `voters.list`, `votes.create`, `votes.delete`, `votes.retrieve`
+- `social.community(…).restricts`: `create`, `delete`
+- `social.community(…).search`: `actors.list`, `hashtags.list`, `posts.list`
+- `social.community(…).webhooks`: `endpoints.create`, `endpoints.delete`, `endpoints.list`, `endpoints.retrieve`, `endpoints.rotateSecret`, `endpoints.test`, `endpoints.update`, `eventTypes.list`, `events.list`, `events.replay`, `events.retrieve`
+- `social.stats`: `retrieve`
+- `social.webhooks`: `endpoints.create`, `endpoints.delete`, `endpoints.list`, `endpoints.retrieve`, `endpoints.rotateSecret`, `endpoints.test`, `endpoints.update`, `eventTypes.list`, `events.list`, `events.replay`, `events.retrieve`
+
+## Pagination
+
+List methods return a `PagePromise`: `for await` walks every item across pages, `await` gives one page.
+
+```ts
+import { Social } from "@productcraft/social";
+const social = new Social({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
+for await (const item of social.communities.list({ limit: 50 })) console.log(item);
+const page = await social.communities.list();
+if (page.hasNextPage()) await page.getNextPage();
+const all = await social.communities.list().toArray({ maxItems: 500 });
+```
 
-## Credentials from the environment
+## Errors
 
-Server-side, omit `auth` and the client reads your workspace key from the environment:
+Every failure is a class you can catch. `APIError` carries `status`, `code`, `message`, `errors[]`, `requestId` and `docUrl`.
 
-```bash
-# .env
-PRODUCTCRAFT_API_KEY=pcft_live_...
+```ts
+import { Social, NotFoundError, RateLimitError, APIError } from "@productcraft/social";
+const social = new Social();
+try {
+  await social.communities.retrieve("00000000-0000-0000-0000-000000000000");
+} catch (err) {
+  if (err instanceof NotFoundError) console.log(err.code, err.requestId, err.docUrl);
+  else if (err instanceof RateLimitError) console.log(err.retryAfter);
+  else if (err instanceof APIError) console.log(err.status, err.errors);
+  else throw err;
+}
 ```
 
-- An explicit `auth` always wins over the environment.
-- Hosts are never read from the environment. Override them in code with `baseUrl`.
-- This is a server-only fallback. Never put a key in `NEXT_PUBLIC_*` or any other variable a bundler inlines into browser code.
+## Retries and timeouts
 
-## Configuration
+Network errors, 408, 429, 5xx and `409 IDEMPOTENCY_IN_PROGRESS` are retried twice by default with exponential backoff and jitter, honouring `Retry-After` up to 60 s. A POST or PATCH without an idempotency key is never retried. Each attempt times out after 60 s, so the worst case with defaults is about 3 minutes; pass `signal: AbortSignal.timeout(ms)` for an overall deadline.
 
-```ts before
-new Social({
-  // Omit to use PRODUCTCRAFT_API_KEY from the environment
-  auth: { type: "apiKey", key: "pcft_live_..." }
-      | { type: "bearer", token: "eyJ..." }
-      | { type: "cookie", value: "auth_token=..." },
-  baseUrl: "https://social.example.test",  // optional override
-  fetch: customFetch,                      // optional
-});
+```ts
+import { Social } from "@productcraft/social";
+const social = new Social({ maxRetries: 3, timeout: 20_000 });
+await social.communities.list({}, { maxRetries: 0, signal: AbortSignal.timeout(5_000) });
 ```
 
-## Common operations
+## Idempotency
 
-### Posts + feeds
+Writes that support it send an `Idempotency-Key` automatically and reuse it on every retry. Pass your own to make a retry across processes safe. If the API's idempotency store is unavailable it runs the request without it (fail-open), so a retry during that window can execute twice.
+
+```ts
+import { Social } from "@productcraft/social";
+const social = new Social({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
+const community = await social.communities.create({ display_name: "My Product Community", slug: "my-product-community" }, { idempotencyKey: "order-1234" });
+```
 
-```ts before
-// Create a post
-await social.client.POST(
-  "/v1/communities/{community_id}/posts",
-  { params: { path: { community_id: communityId } }, body: { text: "..." } },
-);
+## Webhooks
 
-// Get the actor's ranked home feed
-await social.client.GET(
-  "/v1/communities/{community_id}/actors/{actor_id}/feed",
-  { params: { path: { community_id: communityId, actor_id: actorId } } },
-);
+`social.webhooks.unwrap()` verifies the signature against the **raw** body and returns a typed `Social.UnwrapWebhookEvent`. The secret comes from `{ secret }`, the client's `webhookSecret`, or `PRODUCTCRAFT_SOCIAL_WEBHOOK_SECRET`.
 
-// Discover (community-wide ranked feed, not personalised to follows)
-await social.client.GET(
-  "/v1/communities/{community_id}/discover-feed",
-  { params: { path: { community_id: communityId } } },
-);
+Next.js route handler:
 
-// React / unreact / bookmark / quote / repost — same shape, different paths
+```ts
+import { Social } from "@productcraft/social";
+const social = new Social();
+export async function POST(req: Request) {
+  const event = await social.webhooks.unwrap({ payload: await req.text(), headers: req.headers });
+  switch (event.type) {
+    case "actor.updated":
+      console.log(event.data);
+      break;
+    default:
+      break; // UnknownWebhookEvent: types added later
+  }
+  return new Response(null, { status: 204 });
+}
 ```
 
-### Stories
+Express (keep the body raw):
 
-```ts before
-// Post a story (24h TTL)
-await social.client.POST(
-  "/v1/communities/{community_id}/stories",
-  { params: { ... }, body: { media_url: "...", visibility: "close_friends" } },
-);
-
-// Story tray (the bubble row at the top of the home screen)
-await social.client.GET(
-  "/v1/communities/{community_id}/actors/{actor_id}/story-tray",
-  { ... },
-);
+```ts
+import express from "express";
+import { Social } from "@productcraft/social";
+const social = new Social();
+const app = express();
+app.post("/webhooks", express.raw({ type: "application/json" }), async (req, res) => {
+  const event = await social.webhooks.unwrap({ payload: req.body, headers: req.headers });
+  console.log(event.type);
+  res.sendStatus(204);
+});
 ```
 
-### Social graph
-
-```ts before
-// Follow / unfollow
-await social.client.PUT(
-  "/v1/communities/{community_id}/follows/{src_actor_id}/{dst_actor_id}",
-  { ... },
-);
+Hono:
 
-// Block / mute / restrict — same shape, different paths
-// Close friends, hashtag follows, muted terms — all under /actors/{actor_id}/...
+```ts
+import { Hono } from "hono";
+import { Social } from "@productcraft/social";
+const social = new Social();
+const app = new Hono();
+app.post("/webhooks", async (c) => {
+  const event = await social.webhooks.unwrap({ payload: await c.req.text(), headers: c.req.raw.headers });
+  console.log(event.type);
+  return c.body(null, 204);
+});
 ```
 
-### Notifications
-
-```ts before
-// List
-await social.client.GET(
-  "/v1/communities/{community_id}/actors/{actor_id}/notifications",
-  { ... },
-);
-
-// Unread count for the bell badge
-await social.client.GET(
-  "/v1/communities/{community_id}/actors/{actor_id}/notifications/unread-count",
-  { ... },
-);
-
-// Mark all read
-await social.client.POST(
-  "/v1/communities/{community_id}/actors/{actor_id}/notifications/read-all",
-  { ... },
-);
+## Raw responses
+
+Every returned object has a non-enumerable `lastResponse` (`requestId`, `status`, `headers`). `.withResponse()` adds the `Response` and parsed rate-limit headers.
+
+```ts
+import { Social } from "@productcraft/social";
+const social = new Social({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
+const id = "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b";
+const obj = await social.communities.retrieve(id);
+console.log(obj.lastResponse.requestId);
+const { data, response, requestId, rateLimit } = await social.communities.retrieve(id).withResponse();
+console.log(data, response.status, requestId, rateLimit?.remaining);
 ```
 
-### Direct conversations
+## Testing
 
-```ts before
-// Start / open a conversation
-await social.client.POST(
-  "/v1/communities/{community_id}/conversations",
-  { params: { ... }, body: { members: ["act_a", "act_b"] } },
-);
+`@productcraft/social/testing` exports `createMockFetch()`, a `fetch` that answers every operation with its spec example. Override one operation by name.
 
-// Send a message
-await social.client.POST(
-  "/v1/communities/{community_id}/conversations/{conversation_id}/messages",
-  { ... },
-);
+```ts
+import { Social } from "@productcraft/social";
+import { createMockFetch } from "@productcraft/social/testing";
+const fetch = createMockFetch();
+const social = new Social({ apiKey: "test", workspaceId: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b", fetch });
+await social.communities.list();
+console.log(fetch.calls.length);
 ```
 
-### Moderation (workspace admin)
-
-```ts before
-// List flags
-await social.client.GET(
-  "/v1/workspaces/{workspace_id}/communities/{community_id}/moderation/flags",
-  { ... },
-);
-
-// Act on a flag (resolve / dismiss / take action on the target)
-await social.client.POST(
-  "/v1/workspaces/{workspace_id}/communities/{community_id}/moderation/flags/{flag_id}/actions",
-  { params: { ... }, body: { action: "remove_content", note: "..." } },
-);
-
-// Shadow-ban an actor
-await social.client.PUT(
-  "/v1/workspaces/{workspace_id}/communities/{community_id}/moderation/actors/{actor_id}/shadow-ban",
-  { ... },
-);
-```
+## Escape hatch
+
+`.client` is the typed `openapi-fetch` client over the same credential and base URL (no retries). Use it for anything the resource methods do not cover.
 
-## How this SDK is built
+```ts
+import { Social } from "@productcraft/social";
+const social = new Social({ apiKey: process.env.PRODUCTCRAFT_API_KEY });
+const { data, error } = await social.client.GET("/v1/workspaces/{workspace_id}/communities", { params: { path: { workspace_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b" } } });
+console.log(data, error);
+```
 
-Generated from the live OpenAPI spec at `https://social.productcraft.co/docs-json` via [`openapi-typescript`](https://openapi-ts.dev/) + [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/). The nightly `spec-refresh` workflow opens a PR whenever the spec changes.
+<!-- generated:end -->
 
 ## License