@productcraft/social 0.7.1 → 1.0.0

package/README.md

@@ -14,8 +14,8 @@ Social's surface splits two ways — both reach the same data but differ in auth
 
 | Caller | URL prefix | Auth | What you do |
 |---|---|---|---|
-| **PlatformUser admin** | `/v1/workspaces/{workspaceId}/...` | cookie or PAK | Create communities, run moderation, read analytics. |
-| **Customer backend** | `/v1/communities/{communityId}/...` | PAK + `X-Acting-As: <actor_id>` header | Day-to-day reads/writes on behalf of an EndUser. |
+| **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. |
 
 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.
 
@@ -24,14 +24,13 @@ The customer backend acts on behalf of one of its EndUsers via the `X-Acting-As`
 ```ts
 import { Social } from "@productcraft/social";
 
-const social = new Social({
-  auth: { type: "apiKey", key: process.env.PCFT_KEY! },
-});
+// Reads PRODUCTCRAFT_API_KEY from the environment
+const social = new Social();
 
 const { data, error } = await social.client.POST(
-  "/v1/workspaces/{workspaceId}/communities",
+  "/v1/workspaces/{workspace_id}/communities",
   {
-    params: { path: { workspaceId: "<workspace-uuid>" } },
+    params: { path: { workspace_id: "<workspace-uuid>" } },
     body: { display_name: "Founders Club", slug: "founders" },
   },
 );
@@ -43,10 +42,10 @@ const { data, error } = await social.client.POST(
 const actor_id = "<actor-uuid>"; // the EndUser's Social actor id
 
 const { data, error } = await social.client.POST(
-  "/v1/communities/{communityId}/posts",
+  "/v1/communities/{community_id}/posts",
   {
     params: {
-      path: { communityId: "<community-uuid>" },
+      path: { community_id: "<community-uuid>" },
       header: { "X-Acting-As": actor_id },
     },
     body: {
@@ -63,10 +62,42 @@ const { data, error } = await social.client.POST(
 
 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.
 
+## Migrating from 0.x to 1.0
+
+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`:
+
+```ts
+// 0.x
+await social.client.GET("/v1/communities/{communityId}/posts/{postId}", {
+  params: { path: { communityId, postId } },
+});
+
+// 1.0
+await social.client.GET("/v1/communities/{community_id}/posts/{post_id}", {
+  params: { path: { community_id: communityId, post_id: postId } },
+});
+```
+
+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.
+
+## Credentials from the environment
+
+Server-side, omit `auth` and the client reads your workspace key from the environment:
+
+```bash
+# .env
+PRODUCTCRAFT_API_KEY=pcft_live_...
+```
+
+- 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.
+
 ## Configuration
 
 ```ts
 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=..." },
@@ -82,20 +113,20 @@ new Social({
 ```ts
 // Create a post
 await social.client.POST(
-  "/v1/communities/{communityId}/posts",
-  { params: { path: { communityId } }, body: { text: "..." } },
+  "/v1/communities/{community_id}/posts",
+  { params: { path: { community_id: communityId } }, body: { text: "..." } },
 );
 
 // Get the actor's ranked home feed
 await social.client.GET(
-  "/v1/communities/{communityId}/actors/{actorId}/feed",
-  { params: { path: { communityId, actorId } } },
+  "/v1/communities/{community_id}/actors/{actor_id}/feed",
+  { params: { path: { community_id: communityId, actor_id: actorId } } },
 );
 
 // Discover (community-wide ranked feed, not personalised to follows)
 await social.client.GET(
-  "/v1/communities/{communityId}/discover-feed",
-  { params: { path: { communityId } } },
+  "/v1/communities/{community_id}/discover-feed",
+  { params: { path: { community_id: communityId } } },
 );
 
 // React / unreact / bookmark / quote / repost — same shape, different paths
@@ -106,13 +137,13 @@ await social.client.GET(
 ```ts
 // Post a story (24h TTL)
 await social.client.POST(
-  "/v1/communities/{communityId}/stories",
+  "/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/{communityId}/actors/{actorId}/story-tray",
+  "/v1/communities/{community_id}/actors/{actor_id}/story-tray",
   { ... },
 );
 ```
@@ -122,12 +153,12 @@ await social.client.GET(
 ```ts
 // Follow / unfollow
 await social.client.PUT(
-  "/v1/communities/{communityId}/follows/{srcActorId}/{dstActorId}",
+  "/v1/communities/{community_id}/follows/{src_actor_id}/{dst_actor_id}",
   { ... },
 );
 
 // Block / mute / restrict — same shape, different paths
-// Close friends, hashtag follows, muted terms — all under /actors/{actorId}/...
+// Close friends, hashtag follows, muted terms — all under /actors/{actor_id}/...
 ```
 
 ### Notifications
@@ -135,19 +166,19 @@ await social.client.PUT(
 ```ts
 // List
 await social.client.GET(
-  "/v1/communities/{communityId}/actors/{actorId}/notifications",
+  "/v1/communities/{community_id}/actors/{actor_id}/notifications",
   { ... },
 );
 
 // Unread count for the bell badge
 await social.client.GET(
-  "/v1/communities/{communityId}/actors/{actorId}/notifications/unread-count",
+  "/v1/communities/{community_id}/actors/{actor_id}/notifications/unread-count",
   { ... },
 );
 
 // Mark all read
 await social.client.POST(
-  "/v1/communities/{communityId}/actors/{actorId}/notifications/read-all",
+  "/v1/communities/{community_id}/actors/{actor_id}/notifications/read-all",
   { ... },
 );
 ```
@@ -157,13 +188,13 @@ await social.client.POST(
 ```ts
 // Start / open a conversation
 await social.client.POST(
-  "/v1/communities/{communityId}/conversations",
+  "/v1/communities/{community_id}/conversations",
   { params: { ... }, body: { members: ["act_a", "act_b"] } },
 );
 
 // Send a message
 await social.client.POST(
-  "/v1/communities/{communityId}/conversations/{conversationId}/messages",
+  "/v1/communities/{community_id}/conversations/{conversation_id}/messages",
   { ... },
 );
 ```
@@ -173,19 +204,19 @@ await social.client.POST(
 ```ts
 // List flags
 await social.client.GET(
-  "/v1/workspaces/{workspaceId}/communities/{communityId}/moderation/flags",
+  "/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/{workspaceId}/communities/{communityId}/moderation/flags/{flagId}/actions",
+  "/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/{workspaceId}/communities/{communityId}/moderation/actors/{actorId}/shadow-ban",
+  "/v1/workspaces/{workspace_id}/communities/{community_id}/moderation/actors/{actor_id}/shadow-ban",
   { ... },
 );
 ```