@dayofweek/dcli 1.3.0 → 1.5.0

package/dist/client.d.ts

@@ -2,9 +2,16 @@
  * HTTP client for the Day of Week platform REST API.
  * All calls go through the proxy at field.dayofweek.com/app/api/dcli.
  */
+/**
+ * Node's Buffer is a Uint8Array view over a possibly-larger, possibly-shared
+ * backing store, which is not assignable to BodyInit. Copy out the exact bytes.
+ */
+export declare function toArrayBuffer(view: Uint8Array): ArrayBuffer;
 export declare class ApiError extends Error {
     status: number;
-    constructor(status: number, message: string);
+    code?: string | undefined;
+    requestId?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined, requestId?: string | undefined);
 }
 export declare class DayOfWeekClient {
     private baseUrl;
@@ -28,6 +35,75 @@ export declare class DayOfWeekClient {
     revokeDevice(deviceId: string): Promise<{
         success: boolean;
     }>;
+    revokeCurrentDevice(): Promise<{
+        revoked: true;
+    }>;
+    brainBootstrap(): Promise<{
+        authenticated: true;
+        scopes: string[];
+        entitled: boolean;
+        areas: BrainArea[];
+        defaultAreaId?: string;
+    }>;
+    listBrainAreas(): Promise<BrainArea[]>;
+    companyBrainStatus(): Promise<{
+        eligible: boolean;
+        canEnsure: boolean;
+        entityName?: string;
+        existingArea: BrainArea | null;
+    }>;
+    ensureCompanyBrain(): Promise<BrainArea>;
+    resolveBrain(uri: string): Promise<BrainResolvedResource>;
+    getBrainNote(id: string): Promise<BrainNote>;
+    getBrainSource(id: string): Promise<BrainSource>;
+    uploadBrainSource(input: {
+        areaId: string;
+        path: string;
+        mimeType: string;
+        isMeeting: boolean;
+        consentAcknowledged: boolean;
+    }): Promise<{
+        sourceId: string;
+        uri: string;
+        httpsUrl: string;
+        filename: string;
+        byteSize: number;
+        sha256: string;
+        scanState: "pending" | "clean";
+        processingState: string;
+    }>;
+    downloadBrainSource(input: {
+        sourceId: string;
+        outputPath: string;
+        expectedSha256?: string;
+        overwrite?: boolean;
+    }): Promise<{
+        outputPath: string;
+        byteSize: number;
+        sha256: string;
+    }>;
+    searchBrain(query: string, options?: {
+        areaId?: string;
+        limit?: number;
+    }): Promise<unknown>;
+    shareBrainNote(input: {
+        areaId: string;
+        title: string;
+        markdown: string;
+        sourceName?: string;
+        intent: "interactive" | "autonomous";
+    }): Promise<BrainNote>;
+    updateBrainNote(id: string, input: {
+        title?: string;
+        markdown: string;
+        expectedVersion: number;
+    }): Promise<BrainNote>;
+    archiveBrainNote(id: string, expectedVersion: number): Promise<BrainNote>;
+    restoreBrainNote(id: string, expectedVersion: number): Promise<BrainNote>;
+    listBrainAudit(areaId: string, options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<unknown>;
     listEntities(opts?: {
         type?: string;
         parent?: string;
@@ -58,6 +134,7 @@ export declare class DayOfWeekClient {
     getProposal(proposalId: string): Promise<any>;
     submitProposal(proposal: Record<string, unknown>): Promise<any>;
     submitBatch(batch: {
+        org?: string;
         batchLabel: string;
         sourceAgent?: string;
         proposals: any[];
@@ -82,16 +159,142 @@ export declare class DayOfWeekClient {
         truncated: boolean;
         total: number;
     }>;
-    getSkillBundle(): Promise<{
+    /**
+     * List the knowledge documents attached to an entity. `full` returns each
+     * document's whole content instead of an excerpt, which is what you want when
+     * mirroring an entity's sources into an external knowledge base.
+     */
+    listKnowledge(opts: {
+        entity: string;
+        full?: boolean;
+        org?: string;
+    }): Promise<any[]>;
+    getKnowledge(documentId: string, org?: string): Promise<any>;
+    /** Semantic search across knowledge documents. */
+    searchKnowledge(opts: {
+        query: string;
+        entity?: string;
+        types?: string[];
+        limit?: number;
+        allOrgs?: boolean;
+        org?: string;
+    }): Promise<any>;
+    /**
+     * Add a markdown knowledge note.
+     *
+     * Without `direct` this submits a proposal for human review — the default,
+     * and the only option non-admin tokens have. With `direct: true` an admin
+     * token writes the document immediately, skipping review. Ask the operator
+     * before doing that; see references/admin.md in the served skill.
+     */
+    addKnowledge(input: {
+        entityId: string;
+        title: string;
+        content: string;
+        sourceType?: string;
+        sourceUrl?: string;
+        sourceDescription?: string;
+        confidence?: number;
+        sourceAgent?: string;
+        direct?: boolean;
+        org?: string;
+    }): Promise<any>;
+    /**
+     * Attach a binary source (PDF, DOCX, XLSX, …) to an entity. Admin only.
+     *
+     * Three hops: ask for an upload URL, send the bytes straight to Convex
+     * storage, then register the resulting storageId. The bytes never pass
+     * through function arguments, so file size isn't bounded by an arg limit.
+     */
+    attachKnowledgeFile(input: {
+        entityId: string;
+        /** Raw file bytes. Buffer callers: pass `toArrayBuffer(buf)` below. */
+        data: ArrayBuffer;
+        fileName: string;
+        mimeType: string;
+        sourceType?: string;
+        sourceUrl?: string;
+        sourceDescription?: string;
+        org?: string;
+    }): Promise<any>;
+    getSkillBundle(name?: string): Promise<{
         name: string;
         version: string;
+        hash?: string;
         files: Array<{
             path: string;
             content: string;
+            sha256?: string;
         }>;
     }>;
+    listSkillBundles(): Promise<Array<{
+        name: string;
+        version: string;
+        hash: string;
+    }>>;
     getSchema(): Promise<any>;
     private get;
     private post;
+    private put;
+    private patch;
     private delete;
+    private request;
 }
+export type BrainArea = {
+    id: string;
+    name: string;
+    kind: "company" | "project";
+    role: "owner" | "editor" | "viewer";
+    canWrite: boolean;
+    canManage: boolean;
+    uri: string;
+    httpsUrl: string;
+    updatedAt: number;
+};
+export type BrainNote = {
+    id: string;
+    areaId: string;
+    areaName: string;
+    title: string;
+    markdown: string;
+    status: string;
+    version: number;
+    hash?: string;
+    sourceId?: string;
+    sourceUri?: string;
+    uri: string;
+    httpsUrl: string;
+    createdAt: number;
+    updatedAt: number;
+};
+export type BrainSource = {
+    id: string;
+    areaId: string;
+    areaName: string;
+    kind: "text" | "audio" | "file";
+    filename?: string;
+    mimeType?: string;
+    byteSize?: number;
+    sha256?: string;
+    scanState?: "pending" | "clean" | "quarantined" | "failed";
+    processingState: string;
+    rawText?: string;
+    extractedText?: string;
+    transcript?: string;
+    isMeeting: boolean;
+    derivedNoteUri?: string;
+    canDownload: boolean;
+    uri: string;
+    httpsUrl: string;
+    uploadedAt: number;
+};
+export type BrainResolvedResource = {
+    resourceType: "area";
+    area: BrainArea;
+} | {
+    resourceType: "note";
+    note: BrainNote;
+} | {
+    resourceType: "source";
+    source: BrainSource;
+};

package/dist/client.js

@@ -2,12 +2,30 @@
  * HTTP client for the Day of Week platform REST API.
  * All calls go through the proxy at field.dayofweek.com/app/api/dcli.
  */
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, fsyncSync, linkSync, openSync, closeSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 const DEFAULT_BASE_URL = "https://field.dayofweek.com/app/api/dcli";
+/**
+ * Node's Buffer is a Uint8Array view over a possibly-larger, possibly-shared
+ * backing store, which is not assignable to BodyInit. Copy out the exact bytes.
+ */
+export function toArrayBuffer(view) {
+    const out = new ArrayBuffer(view.byteLength);
+    new Uint8Array(out).set(view);
+    return out;
+}
 export class ApiError extends Error {
     status;
-    constructor(status, message) {
+    code;
+    requestId;
+    constructor(status, message, code, requestId) {
         super(message);
         this.status = status;
+        this.code = code;
+        this.requestId = requestId;
         this.name = "ApiError";
     }
 }
@@ -31,6 +49,145 @@ export class DayOfWeekClient {
     async revokeDevice(deviceId) {
         return this.delete(`/auth/devices/${deviceId}`);
     }
+    async revokeCurrentDevice() {
+        return this.delete("/auth/current-device");
+    }
+    // ── Shared brain ─────────────────────────────────────────────────────────
+    async brainBootstrap() {
+        return this.get("/brain/bootstrap");
+    }
+    async listBrainAreas() {
+        return this.get("/brain/areas");
+    }
+    async companyBrainStatus() {
+        return this.get("/brain/company-area");
+    }
+    async ensureCompanyBrain() {
+        return this.post("/brain/company-area", {});
+    }
+    async resolveBrain(uri) {
+        return this.get(`/brain/resolve?uri=${encodeURIComponent(uri)}`);
+    }
+    async getBrainNote(id) {
+        return this.get(`/brain/notes/${encodeURIComponent(id)}`);
+    }
+    async getBrainSource(id) {
+        return this.get(`/brain/sources/${encodeURIComponent(id)}`);
+    }
+    async uploadBrainSource(input) {
+        const info = statSync(input.path);
+        if (!info.isFile())
+            throw new Error("Upload path is not a regular file");
+        const sha256 = await hashFile(input.path);
+        const idempotencyKey = `up_${createHash("sha256")
+            .update(`${input.areaId}:${sha256}:${input.isMeeting}`)
+            .digest("base64url")}`;
+        const session = await this.post("/brain/source-uploads", {
+            areaId: input.areaId,
+            filename: basename(input.path),
+            mimeType: input.mimeType,
+            byteSize: info.size,
+            sha256,
+            isMeeting: input.isMeeting,
+            consentAcknowledged: input.consentAcknowledged,
+            idempotencyKey,
+        });
+        const upload = await fetch(session.uploadUrl, {
+            method: "POST",
+            headers: { "Content-Type": input.mimeType },
+            body: createReadStream(input.path),
+            duplex: "half",
+        });
+        if (!upload.ok)
+            throw new ApiError(upload.status, "Source byte upload failed", "network_error");
+        const stored = await upload.json();
+        if (!stored.storageId)
+            throw new Error("Upload did not return a storage ID");
+        const completed = await this.post(`/brain/source-uploads/${encodeURIComponent(session.uploadId)}/complete`, {
+            storageId: stored.storageId,
+        });
+        if (completed.sha256 !== sha256)
+            throw new Error("Server checksum does not match the uploaded file");
+        return completed;
+    }
+    async downloadBrainSource(input) {
+        if (!input.overwrite && existsSync(input.outputPath))
+            throw new Error("Output already exists; use --overwrite");
+        const response = await fetch(`${this.baseUrl}/brain/sources/${encodeURIComponent(input.sourceId)}/download`, {
+            headers: { Authorization: `Bearer ${this.token}` },
+        });
+        if (!response.ok)
+            throw await apiErrorFromResponse(response);
+        if (!response.body)
+            throw new Error("Download response had no body");
+        const expected = response.headers.get("x-dayofweek-sha256") ?? input.expectedSha256;
+        if (!expected || !/^[a-f0-9]{64}$/.test(expected))
+            throw new Error("Download response omitted its checksum");
+        const tempPath = join(dirname(input.outputPath), `.${basename(input.outputPath)}.dcli-${randomUUID()}.tmp`);
+        const hash = createHash("sha256");
+        let byteSize = 0;
+        const hasher = new Transform({
+            transform(chunk, _encoding, callback) {
+                hash.update(chunk);
+                byteSize += chunk.length;
+                callback(null, chunk);
+            },
+        });
+        try {
+            await pipeline(Readable.fromWeb(response.body), hasher, createWriteStream(tempPath, { flags: "wx", mode: 0o600 }));
+            const descriptor = openSync(tempPath, "r");
+            try {
+                fsyncSync(descriptor);
+            }
+            finally {
+                closeSync(descriptor);
+            }
+            const actual = hash.digest("hex");
+            if (actual !== expected || (input.expectedSha256 && actual !== input.expectedSha256)) {
+                throw new Error("Downloaded source checksum mismatch");
+            }
+            if (input.overwrite) {
+                renameSync(tempPath, input.outputPath);
+            }
+            else {
+                linkSync(tempPath, input.outputPath);
+                unlinkSync(tempPath);
+            }
+            return { outputPath: input.outputPath, byteSize, sha256: actual };
+        }
+        catch (error) {
+            if (existsSync(tempPath))
+                unlinkSync(tempPath);
+            throw error;
+        }
+    }
+    async searchBrain(query, options) {
+        return this.post("/brain/search", {
+            query,
+            areaId: options?.areaId,
+            limit: options?.limit,
+        });
+    }
+    async shareBrainNote(input) {
+        return this.post("/brain/notes", input);
+    }
+    async updateBrainNote(id, input) {
+        return this.patch(`/brain/notes/${encodeURIComponent(id)}`, input);
+    }
+    async archiveBrainNote(id, expectedVersion) {
+        return this.delete(`/brain/notes/${encodeURIComponent(id)}?expectedVersion=${expectedVersion}`);
+    }
+    async restoreBrainNote(id, expectedVersion) {
+        return this.post(`/brain/notes/${encodeURIComponent(id)}/restore`, { expectedVersion });
+    }
+    async listBrainAudit(areaId, options) {
+        const query = new URLSearchParams({ areaId });
+        if (options?.cursor)
+            query.set("cursor", options.cursor);
+        if (options?.limit)
+            query.set("limit", String(options.limit));
+        return this.get(`/brain/audit?${query}`);
+    }
     // ── Read ──────────────────────────────────────────────────────────────────
     async listEntities(opts) {
         const params = new URLSearchParams();
@@ -131,9 +288,94 @@ export class DayOfWeekClient {
         const qs = params.toString();
         return this.get(`/admin/proposals${qs ? `?${qs}` : ""}`);
     }
+    // ── Knowledge ─────────────────────────────────────────────────────────────
+    /**
+     * List the knowledge documents attached to an entity. `full` returns each
+     * document's whole content instead of an excerpt, which is what you want when
+     * mirroring an entity's sources into an external knowledge base.
+     */
+    async listKnowledge(opts) {
+        const params = new URLSearchParams({ entity: opts.entity });
+        if (opts.full)
+            params.set("full", "1");
+        if (opts.org)
+            params.set("org", opts.org);
+        return this.get(`/knowledge?${params.toString()}`);
+    }
+    async getKnowledge(documentId, org) {
+        const params = new URLSearchParams({ document: documentId });
+        if (org)
+            params.set("org", org);
+        return this.get(`/knowledge?${params.toString()}`);
+    }
+    /** Semantic search across knowledge documents. */
+    async searchKnowledge(opts) {
+        const params = new URLSearchParams({ q: opts.query });
+        if (opts.entity)
+            params.set("entity", opts.entity);
+        if (opts.types?.length)
+            params.set("types", opts.types.join(","));
+        if (opts.limit)
+            params.set("limit", String(opts.limit));
+        if (opts.allOrgs)
+            params.set("allOrgs", "1");
+        if (opts.org)
+            params.set("org", opts.org);
+        return this.get(`/knowledge?${params.toString()}`);
+    }
+    /**
+     * Add a markdown knowledge note.
+     *
+     * Without `direct` this submits a proposal for human review — the default,
+     * and the only option non-admin tokens have. With `direct: true` an admin
+     * token writes the document immediately, skipping review. Ask the operator
+     * before doing that; see references/admin.md in the served skill.
+     */
+    async addKnowledge(input) {
+        return this.post("/knowledge", input);
+    }
+    /**
+     * Attach a binary source (PDF, DOCX, XLSX, …) to an entity. Admin only.
+     *
+     * Three hops: ask for an upload URL, send the bytes straight to Convex
+     * storage, then register the resulting storageId. The bytes never pass
+     * through function arguments, so file size isn't bounded by an arg limit.
+     */
+    async attachKnowledgeFile(input) {
+        const { uploadUrl } = await this.post("/knowledge/file", {
+            entityId: input.entityId,
+            org: input.org,
+        });
+        const byteSize = input.data.byteLength;
+        const uploadRes = await fetch(uploadUrl, {
+            method: "POST",
+            headers: { "Content-Type": input.mimeType },
+            body: input.data,
+        });
+        if (!uploadRes.ok) {
+            throw new ApiError(uploadRes.status, `Upload to storage failed: ${uploadRes.status} ${uploadRes.statusText}`);
+        }
+        const uploaded = (await uploadRes.json());
+        if (!uploaded.storageId)
+            throw new Error("Storage upload returned no storageId");
+        return this.put("/knowledge/file", {
+            entityId: input.entityId,
+            org: input.org,
+            storageId: uploaded.storageId,
+            fileName: input.fileName,
+            mimeType: input.mimeType,
+            byteSize,
+            sourceType: input.sourceType,
+            sourceUrl: input.sourceUrl,
+            sourceDescription: input.sourceDescription,
+        });
+    }
     // ── Skill ─────────────────────────────────────────────────────────────────
-    async getSkillBundle() {
-        return this.get("/skill");
+    async getSkillBundle(name) {
+        return this.get(`/skill${name ? `?name=${encodeURIComponent(name)}` : ""}`);
+    }
+    async listSkillBundles() {
+        return this.get("/skill?list=1");
     }
     // ── Schema ────────────────────────────────────────────────────────────────
     async getSchema() {
@@ -141,55 +383,49 @@ export class DayOfWeekClient {
     }
     // ── HTTP helpers ──────────────────────────────────────────────────────────
     async get(path) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            headers: { Authorization: `Bearer ${this.token}` },
-        });
-        if (!res.ok) {
-            const body = await res.text();
-            try {
-                const json = JSON.parse(body);
-                throw new ApiError(res.status, json.error ?? body);
-            }
-            catch (e) {
-                if (e instanceof ApiError)
-                    throw e;
-                throw new ApiError(res.status, body);
-            }
-        }
-        return res.json();
+        return this.request(path, { method: "GET" });
     }
     async post(path, body) {
+        return this.request(path, { method: "POST", body: JSON.stringify(body) });
+    }
+    async put(path, body) {
+        return this.request(path, { method: "PUT", body: JSON.stringify(body) });
+    }
+    async patch(path, body) {
+        return this.request(path, { method: "PATCH", body: JSON.stringify(body) });
+    }
+    async delete(path) {
+        return this.request(path, { method: "DELETE" });
+    }
+    async request(path, init) {
         const res = await fetch(`${this.baseUrl}${path}`, {
-            method: "POST",
+            ...init,
             headers: {
                 Authorization: `Bearer ${this.token}`,
-                "Content-Type": "application/json",
+                ...(init.body ? { "Content-Type": "application/json" } : {}),
+                ...init.headers,
             },
-            body: JSON.stringify(body),
         });
-        if (!res.ok) {
-            const text = await res.text();
-            try {
-                const json = JSON.parse(text);
-                throw new ApiError(res.status, json.error ?? text);
-            }
-            catch (e) {
-                if (e instanceof ApiError)
-                    throw e;
-                throw new ApiError(res.status, text);
-            }
-        }
+        if (!res.ok)
+            throw await apiErrorFromResponse(res);
         return res.json();
     }
-    async delete(path) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
-            method: "DELETE",
-            headers: { Authorization: `Bearer ${this.token}` },
-        });
-        if (!res.ok) {
-            const text = await res.text();
-            throw new ApiError(res.status, text);
-        }
-        return res.json();
+}
+async function hashFile(path) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest("hex");
+}
+async function apiErrorFromResponse(response) {
+    const body = await response.text();
+    try {
+        const json = JSON.parse(body);
+        if (typeof json.error === "string")
+            return new ApiError(response.status, json.error);
+        return new ApiError(response.status, json.error?.message ?? `Request failed (${response.status})`, json.error?.code, json.error?.requestId);
+    }
+    catch {
+        return new ApiError(response.status, `Request failed (${response.status})`);
     }
 }

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import { type CredentialStore } from "./credentials.js";
 export interface DcliConfig {
     authToken?: string;
     apiUrl?: string;
@@ -13,5 +14,7 @@ export interface DcliConfig {
 }
 export declare function loadConfig(): DcliConfig;
 export declare function saveConfig(updates: Partial<DcliConfig>): void;
-export declare function getToken(): string;
+export declare function getToken(store?: CredentialStore): string;
+export declare function saveCredential(secret: string, store?: CredentialStore): void;
+export declare function deleteCredential(store?: CredentialStore): void;
 export declare function getApiUrl(): string;

package/dist/config.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { defaultCredentialStore } from "./credentials.js";
 const CONFIG_DIR = join(homedir(), ".config", "dayofweek");
 const CONFIG_FILE = join(CONFIG_DIR, "dcli.json");
 export function loadConfig() {
@@ -15,22 +16,39 @@ export function loadConfig() {
     return {};
 }
 export function saveConfig(updates) {
-    mkdirSync(CONFIG_DIR, { recursive: true });
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
     const existing = loadConfig();
     const merged = { ...existing, ...updates };
-    writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), "utf-8");
+    writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), { encoding: "utf-8", mode: 0o600 });
 }
-export function getToken() {
+export function getToken(store = defaultCredentialStore()) {
+    const config = loadConfig();
+    const storedToken = store.get();
     const token = process.env.DCLI_AUTH_TOKEN ??
         process.env.DCLI_TOKEN ??
-        loadConfig().authToken;
+        storedToken ??
+        config.authToken;
+    // One-way migration of the old plaintext config. The legacy key is removed
+    // immediately after the protected store accepts it.
+    if (!storedToken && config.authToken && token === config.authToken) {
+        store.set(config.authToken);
+        saveConfig({ authToken: undefined });
+    }
     if (!token) {
-        console.error("No auth token found.");
-        console.error("Set DCLI_AUTH_TOKEN or run: dcli auth login");
-        process.exit(1);
+        throw new Error("No credential found. Run: dcli auth login");
     }
     return token;
 }
+export function saveCredential(secret, store = defaultCredentialStore()) {
+    store.set(secret);
+    if (loadConfig().authToken)
+        saveConfig({ authToken: undefined });
+}
+export function deleteCredential(store = defaultCredentialStore()) {
+    store.delete();
+    if (loadConfig().authToken)
+        saveConfig({ authToken: undefined });
+}
 export function getApiUrl() {
     return (process.env.DCLI_API_URL ??
         loadConfig().apiUrl ??

package/dist/credentials.d.ts

@@ -0,0 +1,13 @@
+export interface CredentialStore {
+    get(): string | undefined;
+    set(secret: string): void;
+    delete(): void;
+}
+export declare class ProtectedFileCredentialStore implements CredentialStore {
+    readonly path: string;
+    constructor(path?: string);
+    get(): string | undefined;
+    set(secret: string): void;
+    delete(): void;
+}
+export declare function defaultCredentialStore(): CredentialStore;