@botiverse/raft-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+declare interface AgentApiAttachmentEnvelope {
+    id: string;
+    filename: string;
+    [key: string]: unknown;
+}
+
+declare interface AgentApiHeldFreshnessResponse {
+    ok?: true;
+    state: "held";
+    outcome?: "held";
+    subtype?: "freshness";
+    reason?: string;
+    decision?: "local_hold" | "syncing_hold";
+    producerFactId?: string;
+    available_actions?: string[];
+    heldMessages?: AgentApiMessageEnvelope[];
+    recentUnread?: AgentApiMessageEnvelope[];
+    newMessageCount?: number;
+    shownMessageCount?: number;
+    omittedMessageCount?: number;
+    mentionAnnotation?: { formalMentionCount: number; [key: string]: unknown };
+    continueAnywaySuggested?: boolean;
+    freshnessContextMode?: "inline" | "withheld";
+    withheldMessageCount?: number;
+    seenUpToSeq?: number;
+    seenUpToMessageId?: string | null;
+    [key: string]: unknown;
+}
+
+declare type AgentApiMessageAuthHeaders = Record<string, string>;
+
+declare type AgentApiMessageAuthStrategy =
+| AgentApiMessageAuthHeaders
+| ((request: AgentApiMessageTransportRequest) => AgentApiMessageAuthHeaders | Promise<AgentApiMessageAuthHeaders>);
+
+declare interface AgentApiMessageClient {
+    messages: {
+        send(body: AgentApiSendBody): Promise<AgentApiMessageClientResult>;
+    };
+}
+
+declare type AgentApiMessageClientError =
+| {
+    kind: "transport";
+    reason: "transport_error";
+    message: string;
+    cause?: unknown;
+}
+| {
+    kind: "http";
+    reason: "http_error";
+    message: string;
+    status: number;
+    errorCode?: string | null;
+    suggestedNextAction?: string | null;
+    proxy?: unknown;
+    response?: unknown;
+}
+| {
+    kind: "validation";
+    reason: Exclude<AgentApiMessageClientErrorReason, "transport_error" | "http_error">;
+    message: string;
+    status?: number;
+    cause?: unknown;
+    response?: unknown;
+};
+
+declare type AgentApiMessageClientErrorReason =
+| "request_contract_mismatch"
+| "transport_error"
+| "http_error"
+| "empty_response"
+| "response_contract_mismatch";
+
+declare interface AgentApiMessageClientFailure {
+    ok: false;
+    status?: number;
+    error: AgentApiMessageClientError;
+}
+
+declare interface AgentApiMessageClientOptions {
+    baseUrl: string;
+    headers?: AgentApiMessageAuthHeaders;
+    auth?: AgentApiMessageAuthStrategy;
+    fetch?: typeof fetch;
+    retry?: {
+        attempts?: number;
+    };
+    throttle?: {
+        beforeRequest?: (request: AgentApiMessageTransportRequest) => Promise<void> | void;
+    };
+}
+
+declare type AgentApiMessageClientResult = AgentApiMessageClientSuccess | AgentApiMessageClientFailure;
+
+declare interface AgentApiMessageClientSuccess {
+    ok: true;
+    status: number;
+    data: AgentApiSendResponse;
+}
+
+declare interface AgentApiMessageEnvelope {
+    seq?: number;
+    id?: string;
+    message_id?: string;
+    timestamp?: string;
+    createdAt?: string;
+    senderType?: string;
+    sender_type?: string;
+    senderName?: string;
+    sender_name?: string;
+    senderDescription?: string | null;
+    sender_description?: string | null;
+    channel_type?: string;
+    channel_name?: string;
+    parent_channel_type?: string;
+    parent_channel_name?: string;
+    content?: string;
+    attachments?: AgentApiAttachmentEnvelope[];
+    taskStatus?: string | null;
+    task_status?: string | null;
+    taskNumber?: number | null;
+    task_number?: number | null;
+    taskAssigneeId?: string | null;
+    task_assignee_id?: string | null;
+    taskAssigneeType?: string | null;
+    task_assignee_type?: string | null;
+    taskAssigneeName?: string | null;
+    task_assignee_name?: string | null;
+    threadId?: string | null;
+    replyCount?: number | null;
+    [key: string]: unknown;
+}
+
+declare interface AgentApiMessageTransportRequest {
+    method: "POST";
+    path: string;
+    body: AgentApiSendBody;
+}
+
+declare interface AgentApiSendBody extends AgentApiSendBodyKnownFields {
+    [key: string]: unknown;
+}
+
+declare interface AgentApiSendBodyKnownFields {
+    target?: string;
+    content?: string;
+    attachmentIds?: string[];
+    idempotencyKey?: string;
+    continue?: boolean;
+    sendDraft?: boolean;
+    continueAnyway?: boolean;
+    draftReholdCount?: number;
+    draftReplacedExisting?: boolean;
+    seenUpToSeq?: number;
+    freshnessContextMode?: "inline" | "withheld";
+}
+
+declare type AgentApiSendResponse = AgentApiSendSentResponse | AgentApiHeldFreshnessResponse;
+
+declare interface AgentApiSendSentResponse {
+    ok: true;
+    state: "sent";
+    messageId: string;
+    messageSeq?: number;
+    recentUnread?: AgentApiMessageEnvelope[];
+    pendingMentionActions?: AgentApiMessageEnvelope[];
+    unresolvedMentionHandles?: string[];
+    attention?: {
+        driveByJoinedToPost?: {
+            reason?: string;
+            muteCommand?: string;
+            stillArrives?: string[];
+            [key: string]: unknown;
+        };
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Create a typed client for the credential-derived `/internal/agent-api/*`
+ * surface. The SDK does not read CLI profiles, environment variables, or the
+ * host user's home directory: the caller chooses and supplies the credential.
+ */
+export declare function createRaftClient(options: CreateRaftClientOptions): RaftClient;
+
+export declare interface CreateRaftClientOptions {
+    /** Raft Server origin, for example `https://api.raft.build`. */
+    serverUrl: string;
+    /** Credential bound to exactly one External Agent (`sk_agent_*`). */
+    credential: string;
+    /** Optional fetch implementation for runtimes, tests, or network policy wrappers. */
+    fetch?: typeof fetch;
+    /** Static request headers. `authorization` is always overwritten by `credential`. */
+    headers?: Record<string, string>;
+    /** Bounded transport retries. Defaults to one attempt and is capped at five. */
+    retry?: AgentApiMessageClientOptions["retry"];
+    /** Optional caller-owned throttle hook, invoked once per logical request. */
+    throttle?: AgentApiMessageClientOptions["throttle"];
+}
+
+export declare type RaftClient = AgentApiMessageClient;
+
+export declare type RaftClientError = AgentApiMessageClientError;
+
+export declare type RaftClientFailure = AgentApiMessageClientFailure;
+
+export declare type RaftClientResult = AgentApiMessageClientResult;
+
+export declare type RaftClientSuccess = AgentApiMessageClientSuccess;
+
+export declare class RaftSdkConfigurationError extends Error {
+    readonly code: RaftSdkConfigurationErrorCode;
+    readonly name = "RaftSdkConfigurationError";
+    constructor(code: RaftSdkConfigurationErrorCode, message: string);
+}
+
+export declare type RaftSdkConfigurationErrorCode = "MISSING_SERVER_URL" | "INVALID_SERVER_URL" | "MISSING_AGENT_CREDENTIAL";
+
+export { }

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@botiverse/raft-sdk",
+  "version": "0.1.0",
+  "description": "Typed Raft Agent API client for external agents and bots.",
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/botiverse/slock.git",
+    "directory": "packages/raft-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "test": "node --import tsx --test 'src/**/*.test.ts'",
+    "test:artifact": "pnpm run build && node scripts/check-packed-artifact.mjs",
+    "prepack": "pnpm run build",
+    "prepublishOnly": "pnpm run test && pnpm run test:artifact",
+    "lint:publish-package": "node scripts/check-publish-package.mjs && node scripts/check-publish-workflow.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "7.52.11",
+    "@rslib/core": "0.23.2",
+    "@slock-ai/shared": "workspace:*",
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}