@recursiv/sdk 0.7.62 → 0.7.63

package/README.md

@@ -99,7 +99,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.chat` | `send`, `dm`, `createGroup` (`encrypted: true` for an end-to-end encrypted group, 0.7.59), `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation`; a private group's admin: `addMembers`, `removeMember`, `updateGroup` (0.7.59) |
 | `r.tags` | `create`, `list` |
 | `r.uploads` | `uploadMedia` — upload post/chat bytes end to end |
-| `r.video` | `entitlement` (may the caller publish video, and how much is left), `createUpload`, `getStatus`, `getPlaybackToken` |
+| `r.video` | `entitlement` (may the caller publish video, and how much is left), `createUpload`, `renewUpload` (the creator's fresh TUS credentials for the same video, with `createUpload`'s `resumeGrant`, so a resume past the hour continues it; 0.7.63), `getStatus`, `getPlaybackToken` |
 
 ### Platform
 | Resource | Purpose |

package/dist/index.d.ts

@@ -235,7 +235,7 @@ export type { Brief, BriefEmail, MyBrief, MyBriefEntry, BriefParams, BriefShippe
 export type { HumanAsk, HumanAskStatus, CreateHumanAskInput, ListHumanAsksParams } from './resources/human-asks.js';
 export { HumanInputResource } from './resources/human-input.js';
 export type { Goal, GoalTask, CreateGoalInput, UpdateGoalInput, ListGoalsParams, ReorderGoalTasksInput } from './resources/goals.js';
-export type { DispatcherTask, TaskClaim, ClaimRecord, DispatcherStats, CreateTaskInput, UpdateTaskInput, ListTasksParams, SignalRecord, OutcomeRecord, PauseState, PauseInput, SignalsParams, OutcomesParams, DiscoveryParams, StaleStuckParams } from './resources/dispatcher.js';
+export type { DispatcherTask, TaskClaim, ClaimRecord, DispatcherStats, CreateTaskInput, UpdateTaskInput, ListTasksParams, SignalRecord, OutcomeRecord, PauseState, PauseInput, SignalsParams, OutcomesParams, DiscoveryParams, StaleStuckParams, TaskPlan, TaskPlanStep, SetTaskPlanInput, UpdateTaskPlanStepInput } from './resources/dispatcher.js';
 export { SwarmsResource } from './resources/swarms.js';
 export type { Swarm, SwarmMember, CreateSwarmInput, ListSwarmsParams, ScheduledTask, ScheduleTaskInput } from './resources/swarms.js';
 export { TemplatesResource } from './resources/templates.js';

package/dist/resources/dispatcher.d.ts

@@ -1,5 +1,54 @@
 import type { HttpClient } from '../client.js';
 import type { SingleResponse, DeleteResponse, PaginationParams } from '../types.js';
+/** One step of a task's plan, as the checklist card shows it. */
+export interface TaskPlanStep {
+    position: number;
+    title: string;
+    status: 'pending' | 'in_progress' | 'done' | 'skipped' | 'blocked';
+    /** Why a step is blocked or was skipped. */
+    reason: string | null;
+    /** The specialist agent doing the step. */
+    agent: {
+        id: string;
+        name: string;
+    } | null;
+    /** The approval or question a blocked step waits on, in the plan's conversation. */
+    waitingOn: {
+        executionId: string | null;
+        messageId: string | null;
+    } | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+export interface TaskPlan {
+    taskId: string;
+    title: string;
+    /** The chat the plan's card lives in. */
+    conversationId: string | null;
+    steps: TaskPlanStep[];
+}
+export interface SetTaskPlanInput {
+    agent?: string;
+    /** The chat to post the card in. Only the first plan that names one posts it. */
+    conversation_id?: string | null;
+    steps: Array<{
+        title: string;
+        agent_id?: string | null;
+    }>;
+    organization_id?: string;
+}
+export interface UpdateTaskPlanStepInput {
+    agent?: string;
+    status: TaskPlanStep['status'];
+    title?: string;
+    /** Kept only for 'blocked' and 'skipped'. */
+    reason?: string | null;
+    /** Only for 'blocked': the approval it waits on. */
+    waiting_on_execution_id?: string | null;
+    /** Only for 'blocked': the question message it waits on. */
+    waiting_on_message_id?: string | null;
+    organization_id?: string;
+}
 export interface DispatcherTask {
     id: string;
     title: string;
@@ -275,6 +324,13 @@ export declare class DispatcherResource {
     }): Promise<SingleResponse<{
         ok: true;
     }>>;
+    /**
+     * Write a claimed task's step plan (the checklist card). Replaces every step
+     * that has not finished; done and skipped steps stay. Requires the claim.
+     */
+    setPlan(taskId: string, input: SetTaskPlanInput): Promise<SingleResponse<TaskPlan>>;
+    /** Move one step of a claimed task's plan. Started and finished times are stamped server-side. */
+    updatePlanStep(taskId: string, position: number, input: UpdateTaskPlanStepInput): Promise<SingleResponse<TaskPlan>>;
     /**
      * Mark a task as done. A task with a thresholded check that has no passing
      * run refuses with 409 and the failing check names — run

package/dist/resources/dispatcher.js

@@ -28,6 +28,19 @@ export class DispatcherResource {
         const { organization_id, ...body } = input;
         return this.client.post(`/dispatcher/heartbeat/${encodeURIComponent(taskId)}${orgQuery(organization_id)}`, body);
     }
+    /**
+     * Write a claimed task's step plan (the checklist card). Replaces every step
+     * that has not finished; done and skipped steps stay. Requires the claim.
+     */
+    setPlan(taskId, input) {
+        const { organization_id, ...body } = input;
+        return this.client.put(`/dispatcher/tasks/${encodeURIComponent(taskId)}/plan${orgQuery(organization_id)}`, body);
+    }
+    /** Move one step of a claimed task's plan. Started and finished times are stamped server-side. */
+    updatePlanStep(taskId, position, input) {
+        const { organization_id, ...body } = input;
+        return this.client.patch(`/dispatcher/tasks/${encodeURIComponent(taskId)}/plan/steps/${position}${orgQuery(organization_id)}`, body);
+    }
     /**
      * Mark a task as done. A task with a thresholded check that has no passing
      * run refuses with 409 and the failing check names — run

package/dist/resources/e2ee.d.ts

@@ -95,9 +95,13 @@ export interface E2eeEvent {
  * quiet one; never a commit, never a Welcome, never one whose envelope is over
  * 16 KB), and only on a socket whose credential could read it with `events()`:
  * one authenticated by the account owner's session or by an owner key whose
- * app or organization binding reaches the conversation. A socket opened with
- * an agent-scoped key gets the content-free form only. When present it is the
- * stored event exactly as `events()` returns it, JSON byte for byte.
+ * app or organization binding reaches the conversation, once that sign-in has
+ * called `registerDevice`, `publishKeyPackages`, `keyPackageStatus`,
+ * `events`, `acknowledge` or `appendEvent` for one of the account's active
+ * devices since the socket connected, as a sync after connecting does. A
+ * socket opened with an agent-scoped key, or whose sign-in spoke only for a
+ * device since revoked, gets the content-free form only. When present it is
+ * the stored event exactly as `events()` returns it, JSON byte for byte.
  *
  * With the shared engine, hand `event` to `applyPushed(conversationId, event)`
  * on the device session: it applies the event without a relay read when it is

package/dist/resources/human-input.d.ts

@@ -11,6 +11,10 @@ export interface RequestHumanInputInput {
     steps: string;
     /** One-tap answers (2-4 short words) — rendered as buttons on the phone. */
     options?: string[];
+    /** The option you recommend; must be one of `options`. Marked "Recommended" on the card. */
+    recommended?: string;
+    /** You keep working on `recommended` unless the human answers otherwise. Needs `recommended`. */
+    continuing_with_default?: boolean;
 }
 export interface HumanInputRequest {
     conversation_id: string;

package/dist/resources/protocols.d.ts

@@ -982,6 +982,13 @@ export interface SocialPost {
     author: Omit<SocialProfile, 'subscription'>;
     text: string;
     createdAt: string;
+    /**
+     * The language the post declares, as the lower-case primary subtag of its BCP-47 tag ("de", "en", "pt"): Bluesky's
+     * record `langs[0]`, a Mastodon status's `language`, a Nostr note's NIP-32 `ISO-639-1` self-label. Absent when the post
+     * declares none (most Nostr notes) or a malformed one, and on posts served from the open-network source index; the
+     * server never guesses it from the text and never drops a post for it. Use it to order the viewer's language first.
+     */
+    language?: string;
     replyCount: number | null;
     likeCount: number | null;
     repostCount: number | null;

package/dist/resources/video.d.ts

@@ -13,6 +13,12 @@ export interface CreateVideoUploadResult {
     upload: VideoUploadCreds;
     /** The HLS URL the video will play from once encoding completes. */
     hlsUrl: string;
+    /**
+     * The creator's proof for `renewUpload` (valid 24 h): pass it back to get
+     * fresh credentials for this same video when a resume outlives the hour
+     * `upload` is signed for. Absent from servers older than 0.7.63's API.
+     */
+    resumeGrant?: string;
 }
 export interface VideoStatusInfo {
     status: string | null;
@@ -59,6 +65,20 @@ export declare class VideoResource {
     }): Promise<{
         data: CreateVideoUploadResult;
     }>;
+    /**
+     * Fresh upload credentials for a video this member started, so a TUS resume
+     * that outlives the hour `upload` is signed for continues the same video.
+     * Pass the `resumeGrant` from `createUpload`. 404 for anyone else's video, an
+     * expired grant or an older API without the route; 409 `upload_finished` once
+     * a post carries the video or Bunny holds the whole file; 402 as `createUpload`;
+     * 503 when the video provider could not answer: keep the partial upload and
+     * retry (it never means the video is gone).
+     */
+    renewUpload(playbackId: string, input: {
+        grant: string;
+    }): Promise<{
+        data: CreateVideoUploadResult;
+    }>;
     /** Encode status + metadata for a video. */
     getStatus(playbackId: string): Promise<{
         data: VideoStatusInfo;

package/dist/resources/video.js

@@ -19,6 +19,18 @@ export class VideoResource {
     createUpload(input) {
         return this.client.post('/video/create-upload', input ?? {});
     }
+    /**
+     * Fresh upload credentials for a video this member started, so a TUS resume
+     * that outlives the hour `upload` is signed for continues the same video.
+     * Pass the `resumeGrant` from `createUpload`. 404 for anyone else's video, an
+     * expired grant or an older API without the route; 409 `upload_finished` once
+     * a post carries the video or Bunny holds the whole file; 402 as `createUpload`;
+     * 503 when the video provider could not answer: keep the partial upload and
+     * retry (it never means the video is gone).
+     */
+    renewUpload(playbackId, input) {
+        return this.client.post(`/video/${encodeURIComponent(playbackId)}/renew-upload`, input);
+    }
     /** Encode status + metadata for a video. */
     getStatus(playbackId) {
         return this.client.get(`/video/${playbackId}/status`);

package/dist/types.d.ts

@@ -649,9 +649,15 @@ export interface ConversationMember {
      */
     role?: ChatMemberRole;
     /**
-     * In a private group, every member's request: `pending` until an invitee
-     * accepts. Declining stays private, so to anyone else a member who declined
-     * still reads `pending`. Omitted outside private groups and by older APIs.
+     * Each member's message request, in a private group or a one-on-one chat.
+     * Someone who follows the person who wrote (or who made the group), and an
+     * agent, start `accepted`, as the person who wrote does; a chat started
+     * without a request reads `accepted` for both. Anyone else starts `pending`
+     * and reads `accepted` once they accept or reply, or, in a one-on-one chat,
+     * start a chat back. So `accepted` alone does not mean they accepted
+     * anything. Declining stays private: to anyone else a member who declined
+     * still reads `pending`. Omitted in community rooms and by older APIs
+     * (one-on-one chats: before this field was served for them).
      */
     request_status?: ChatRequestStatus;
 }

package/llm.md

@@ -502,7 +502,7 @@ Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `
 
 Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growing `offset`. Conversations carry `can_delete` / `can_leave`; check them before offering Delete or Leave.
 
-Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group, `request_status`. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
+Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group or a one-on-one chat, `request_status`: `accepted` from the start for the person who wrote, anyone who follows them and agents, else `pending` until that person accepts or replies (a decline reads `pending` to anyone else), so `accepted` alone does not mean they accepted anything. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
 
 ### r.e2ee — End-to-end encryption transport (flag-gated)
 
@@ -685,7 +685,13 @@ the presign/PUT sequence in application code.
 
 Video: check `const { data } = await r.video.entitlement()` before offering the
 picker (`data.allowed`, `data.reason` 'tier' | 'quota', `data.remainingSeconds`),
-then `r.video.createUpload()`, which runs the same check.
+then `r.video.createUpload()`, which runs the same check. Upload in chunks
+(tus `chunkSize`) and keep the result for the attached file: a retry resumes the
+same video. The TUS signature lasts an hour; past it, call
+`r.video.renewUpload(playbackId, { grant: result.resumeGrant })` (0.7.63) for fresh
+credentials for the same video. 404 (not yours, expired grant, older API) or 409
+`upload_finished` means start a new upload instead. 503 means the video provider
+could not answer: keep the partial upload and ask again later (`Retry-After`).
 
 ### r.chat — Messaging
 
@@ -700,7 +706,7 @@ Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `
 
 Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growing `offset`. Conversations carry `can_delete` / `can_leave`; check them before offering Delete or Leave.
 
-Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group, `request_status`. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
+Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group or a one-on-one chat, `request_status`: `accepted` from the start for the person who wrote, anyone who follows them and agents, else `pending` until that person accepts or replies (a decline reads `pending` to anyone else), so `accepted` alone does not mean they accepted anything. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
 
 ### r.tags
 
@@ -752,6 +758,7 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
   - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows. Category depth: `r.posts.list({ category: 'science', sort: 'hot', discovery: true })` pages the hot window by offset and then by keyset (`meta.next` is `{ offset }`, `{ cursor }` or `null`; pass a cursor back as `cursor`); when a stage ends, `meta.fallover` lists the next feeds in order (`category_older`, `category_network`, `category` with `via`, `for_you`, `all`; `feed` with `ref` is declared in 0.7.60 but not sent yet, so skip kinds you cannot open). One call for a category's modules: `const { data } = await r.discovery.category({ category: 'science' })` returns `stories`, `network`, `clips`, `people`, `groups`, each `{ items, ms, reason? }`. Watch's Minds videos: `const { data, meta } = await r.discovery.videos({ limit: 12 })` returns public video posts in hot order from a list shared per app (rebuilt about once a minute), each re-checked per call for the viewer; page on `meta.next_cursor`.
   - Viral read (0.7.59; off until the server enables it for the app): `const { data } = await r.protocols.getPublicViral({ media: 'video', category: 'science', limit: 20 })` (member key, users:read + posts:read, never cached) or keyless `visitor.protocols.getSharedViral(projectId, { media: 'video', compass: 'hide' })` (visitors send compass `all` or `hide` only). Params, all optional: `network` (all, minds, bluesky, activitypub, nostr), `category`, `media: 'video'`, `limit` 5/10/20/40, `cursor` (the last page's; a cursor whose 30-minute build expired ends the list), `compass`. Each item: `key` (stable; drop ones already shown), `protocol`, `post` (checking `protocol` narrows it: `ViralMindsCard` for minds, open at /post/:id; otherwise a `SocialPost`), `label` viral/rising/hot, `score`, `rank`, `category`, `velocity` (show counts with `countsReportedBy` as reported, never verified), `spread`. A visitor's read serves media only where the server cleared it, so even with `media: 'video'` some items arrive with the video withheld (empty `media`): `import { viralItemHasVideo } from '@recursiv/sdk'` and keep `data.items.filter(viralItemHasVideo)` before a vertical video player. `status` ok/building/screening/off: off resolves with no items, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401/403 (never off), so catch it and skip that step.
   - Public trends: require `public_trends` from `publicNetworks()`, then `getPublicTrends({ protocol, limit?, cursor?, compass? })` (`compass: 'hide'` leaves out politics, 0.7.62); render `kind: topics` as source topics and `kind: posts` as source posts. With `trend_feed`, open only a returned current topic using `getPublicTrendFeed({ protocol, topic: trend.nativeId, limit?, cursor? })`. Show provider, observedAt and provider_ranked_window coverage; null rankingWindow is unknown, not a daily/global ranking. Preserve source order, canonical IDs and readRef, and opaque cursors. Topic catalogs do not paginate; Mastodon trends stop at 200 source positions. Both methods require users:read plus posts:read on the current human app key; Nostr trends are unsupported. Propagate errors; trend_unavailable means refresh the topic list. No ingestion or native writes.
+  - Post language: a `SocialPost` may carry `language`, the lower-case primary subtag the post declares (`'de'`, `'en'`; Bluesky `langs[0]`, Mastodon `language`, a Nostr NIP-32 `ISO-639-1` label). It is absent when the post declares none (most Nostr notes) and on posts from the source index; it is never guessed and no post is dropped for it. Order by it (the viewer's language first, undeclared next), never filter on it.
   - `listCandidates({ protocol?, limit?, cursor? })` and `getCandidate(id)` are read-only quarantine review, not published-post search. Both require `admin` scope, a project-bound key, a live admin role, and existing project-admin access. The key supplies app/network scope; neither method accepts another project or network. They never invoke refresh, change settings, or publish.
   - Lists return `{ data: ProtocolQuarantinedCandidate[], meta: { limit, has_more, next_cursor } }`; use the opaque `next_cursor`, not offset pagination. The API defaults `limit` to 20 and permits at most 50. Details return `{ data: ProtocolQuarantinedCandidate }`. Every candidate has `state: 'quarantined'` and `content_format: 'plain'`; render its bounded `content` as text, respect `content_truncated`, and distinguish upstream `published_at` from local `observed_at` / `created_at`.
   - Safe source IDs are preserved byte-exact. `external_id: null` means unsafe or malformed provenance was withheld, not an invented ID; `author.native_id` may likewise be absent or withheld. Preserve nulls in both list and detail views, and use the candidate's own `id` for `getCandidate`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recursiv/sdk",
-  "version": "0.7.62",
+  "version": "0.7.63",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",