@nextclaw/bibo-api 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @nextclaw/bibo-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Public Bibo space API client. Node 22+ and modern fetch runtimes. No model access is required.
+
+```js
+import { BiboApi } from '@nextclaw/bibo-api';
+const bibo = new BiboApi({ token: process.env.BIBO_API_TOKEN });
+console.log(await bibo.me());
+console.log(await bibo.call('task.list', { open: true }));
+```
+
+Create a scoped token in Bibo → account menu → 接入与授权. Keep tokens private.
+[Documentation](https://app.bibo.bot/docs/) · [Source](https://github.com/Peiiii/bibo)

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+export type * from "./space.types.js";
+export type BiboScope = "space:read" | "space:write";
+export type BiboIntegration = {
+    id: string;
+    name: string;
+    scopes: BiboScope[];
+    createdAt: string;
+    expiresAt: string;
+    lastUsedAt: string | null;
+};
+export type BiboIdentity = {
+    userId: string;
+    integration: BiboIntegration;
+};
+export type BiboActionDefinition = {
+    action: string;
+    domain: string;
+    description: string;
+    input: string;
+    readOnly: boolean;
+};
+export declare class BiboApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string | undefined;
+    readonly retryAfter?: number | undefined;
+    constructor(message: string, status: number, code: string, requestId?: string | undefined, retryAfter?: number | undefined);
+}
+/** Origins only: credentials must never follow an arbitrary path or redirect. */
+export declare function normalizeBiboEndpoint(value?: string): string;
+export declare class BiboApi {
+    readonly endpoint: string;
+    private readonly token;
+    private readonly fetcher;
+    private readonly timeoutMs;
+    constructor(options: {
+        token: string;
+        endpoint?: string;
+        fetch?: typeof fetch;
+        timeoutMs?: number;
+    });
+    private response;
+    private json;
+    me: () => Promise<BiboIdentity>;
+    actions: () => Promise<BiboActionDefinition[]>;
+    call: <T = unknown>(action: string, input?: Record<string, unknown>) => Promise<T>;
+    revoke: () => Promise<{
+        revoked: string;
+    }>;
+    uploadAsset: (bytes: Uint8Array) => Promise<{
+        id: string;
+        url: string;
+        webUrl: string;
+    }>;
+    downloadAsset: (id: string) => Promise<Uint8Array>;
+}

package/dist/index.js

@@ -0,0 +1,77 @@
+export class BiboApiError extends Error {
+    status;
+    code;
+    requestId;
+    retryAfter;
+    constructor(message, status, code, requestId, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.retryAfter = retryAfter;
+        this.name = "BiboApiError";
+    }
+}
+/** Origins only: credentials must never follow an arbitrary path or redirect. */
+export function normalizeBiboEndpoint(value = "https://app.bibo.bot") {
+    const url = new URL(value);
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) || url.username || url.password
+        || url.search || url.hash || (url.pathname !== "/" && url.pathname !== "")) {
+        throw new Error("Endpoint must be an HTTPS origin (HTTP is allowed only on loopback).");
+    }
+    return url.origin;
+}
+export class BiboApi {
+    endpoint;
+    token;
+    fetcher;
+    timeoutMs;
+    constructor(options) {
+        this.endpoint = normalizeBiboEndpoint(options.endpoint);
+        if (!options.token || /\s/.test(options.token))
+            throw new Error("A Bibo access token is required.");
+        this.token = options.token;
+        this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+    }
+    async response(path, init = {}) {
+        let response;
+        try {
+            response = await this.fetcher(`${this.endpoint}/api/v1/${path}`, {
+                ...init, redirect: "error", credentials: "omit",
+                signal: init.signal ?? AbortSignal.timeout(this.timeoutMs),
+                headers: { ...Object.fromEntries(new Headers(init.headers)), authorization: `Bearer ${this.token}` },
+            });
+        }
+        catch {
+            throw new BiboApiError("Could not reach Bibo. Check the endpoint and connection.", 0, "NETWORK_ERROR");
+        }
+        if (!response.ok) {
+            const value = await response.json().catch(() => null);
+            throw new BiboApiError(value?.error?.message ?? `Bibo request failed (${response.status}).`, response.status, value?.error?.code ?? "HTTP_ERROR", value?.requestId, Number(response.headers.get("retry-after")) || undefined);
+        }
+        return response;
+    }
+    async json(path, init) {
+        const response = await this.response(path, init);
+        const value = await response.json().catch(() => null);
+        if (!value || !("result" in value))
+            throw new BiboApiError("Invalid Bibo response.", response.status, "INVALID_RESPONSE");
+        return value.result;
+    }
+    me = () => this.json("me");
+    actions = () => this.json("actions");
+    call = (action, input = {}) => this.json("space", {
+        method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ action, input }),
+    });
+    revoke = () => this.json("auth/revoke", { method: "POST" });
+    uploadAsset = (bytes) => this.json("assets", {
+        method: "POST", headers: { "content-type": "application/octet-stream" }, body: new Uint8Array(bytes).buffer,
+    });
+    downloadAsset = async (id) => {
+        if (!/^[a-f0-9-]{36}$/.test(id))
+            throw new Error("Invalid asset ID.");
+        return new Uint8Array(await (await this.response(`assets/${id}`)).arrayBuffer());
+    };
+}

package/dist/space.types.d.ts

@@ -0,0 +1,101 @@
+export type BiboSpaceDomain = "projects" | "tasks" | "events" | "inbox" | "files" | "notes";
+export type BiboProject = {
+    id: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+    version: number;
+};
+export type BiboSubtask = {
+    id: string;
+    title: string;
+    done: boolean;
+};
+export type BiboTask = {
+    id: string;
+    projectId: string | null;
+    title: string;
+    description: string;
+    status: "planned" | "active" | "done" | "cancelled";
+    priority: "low" | "medium" | "high";
+    startAt: string | null;
+    completedAt: string | null;
+    dueAt: string | null;
+    subtasks: BiboSubtask[];
+    source: {
+        kind: "user" | "agent";
+        sessionId?: string;
+        integrationId?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    version: number;
+};
+export type BiboEvent = {
+    id: string;
+    title: string;
+    description: string;
+    startAt: string;
+    endAt: string;
+    source: {
+        kind: "user" | "agent";
+        sessionId?: string;
+        integrationId?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    version: number;
+};
+export type BiboInboxItem = {
+    id: string;
+    kind: "agent" | "reminder" | "decision";
+    title: string;
+    body: string;
+    source: {
+        kind: "bibo" | "session" | "task" | "event" | "file";
+        id?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    readAt: string | null;
+    resolvedAt: string | null;
+    version: number;
+};
+export type BiboFile = {
+    id: string;
+    path: string;
+    kind: "folder" | "note" | "document" | "artifact";
+    createdAt: string;
+    updatedAt: string;
+    version: number | string;
+};
+export type BiboFileDetail = BiboFile & {
+    content: string | null;
+    uri: string;
+    preview?: {
+        totalBytes: number;
+        readBytes: number;
+        truncated: boolean;
+        binary: boolean;
+    };
+};
+export type BiboOverview = {
+    inbox: BiboInboxItem[];
+    events: BiboEvent[];
+    tasks: BiboTask[];
+    notes: BiboFile[];
+    projects: Array<{
+        id: string;
+        name: string;
+        total: number;
+        done: number;
+    }>;
+    counts: {
+        unread: number;
+        activeTasks: number;
+    };
+};
+export type BiboSpaceAction = {
+    action: string;
+    input?: Record<string, unknown>;
+};

package/dist/space.types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@nextclaw/bibo-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Bibo public space API client and shared types",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Peiiii/bibo.git",
+    "directory": "packages/bibo-api"
+  },
+  "homepage": "https://app.bibo.bot/docs/",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "tsx": "^4.21.0",
+    "@types/node": "^24.13.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "tsc": "tsc -p tsconfig.check.json --noEmit",
+    "test": "tsx --test src/*.test.ts"
+  }
 }