@mirrowel/opencode-openshare 0.0.0-stage → 0.1.1

package/dist/share-flow.d.ts

@@ -0,0 +1,287 @@
+import { saveServerEntry, deleteServerEntry, type ShareConfig, type ServerEntry } from "./config.js";
+import type { ClientApi, SessionInfo, SessionOpts } from "./core.js";
+import type { ShareHostApi } from "./tui-host.js";
+export type SessionBinding = {
+    id: string;
+    secret: string;
+    rev: number;
+    url: string;
+    enabled?: boolean;
+    opts?: SessionOpts;
+};
+export declare const CONSENT_KV_KEY = "openshare_consent";
+export declare function pluginConfigPaths(baseDir?: string): string[];
+export declare function currentConfig(baseDir?: string): ShareConfig;
+/** Writes the config file. Target rule (owner-directed): the global
+ * settings home by default, or an explicit existing file chosen in the
+ * TUI — NEVER "first existing in the read chain" (that wrote TUI edits
+ * into the tracked adjacent template, live-caught). $comment and foreign
+ * keys preserved. */
+export declare function saveConfig(cfg: ShareConfig, target?: string, baseDir?: string): {
+    path: string;
+} | undefined;
+export declare function isConfigured(cfg: ShareConfig): boolean;
+/** The resolved active server (url + entry), for the TUI server rows. */
+export declare function activeServer(cfg?: ShareConfig): {
+    url: string;
+    token: string;
+    entry: ServerEntry;
+} | undefined;
+export declare function serverEntries(cfg?: ShareConfig): Array<{
+    url: string;
+    entry: ServerEntry;
+    active: boolean;
+}>;
+export { saveServerEntry, deleteServerEntry };
+/** All live per-server bindings from a v2 (or legacy v1) metadata record. */
+export declare function bindingsOf(info: SessionInfo | undefined): Array<SessionBinding & {
+    server: string;
+    collided?: string;
+}>;
+/** Read every live binding for a session (fan-out aware). */
+export declare function readBindings(client: ClientApi | undefined, sid: string): Promise<Array<SessionBinding & {
+    server: string;
+    collided?: string;
+}>>;
+export declare function hostOf(url: string): string;
+/** Mutate metadata.openshare.servers[url] through a patcher (TUI per-
+ * server actions: opt-out entries, collision resolution). Reads-modifies-
+ * writes the whole metadata to keep foreign keys intact. */
+export declare function patchSessionBinding(client: ClientApi | undefined, sid: string, mutator: (servers: Record<string, unknown>, binding: Record<string, unknown>) => void): Promise<boolean>;
+/** The display/primary binding: the active server's entry when bound
+ * there, else the first live entry (single-server configs are unchanged). */
+export declare function bindingOf(info: SessionInfo | undefined): SessionBinding | undefined;
+/** Walks parentID up to the root session (the share owns the whole tree). */
+export declare function resolveRoot(client: ClientApi | undefined, sid: string): Promise<string>;
+export declare function readBinding(client: ClientApi | undefined, sid: string): Promise<SessionBinding | undefined>;
+/** Sets metadata.openshare = { ...existing(v2 structure preserved),
+ * enabled: true, opts? }. The per-server binding entries are the ENGINE's
+ * to manage; the flag just opts the session in. */
+export declare function setShareFlag(client: ClientApi | undefined, sid: string, opts?: SessionOpts): Promise<boolean>;
+export declare function clearShareFlag(client: ClientApi | undefined, sid: string): Promise<boolean>;
+export declare function workerDeleteShare(workerUrl: string, id: string, secret: string): Promise<boolean>;
+/** Health probe for the settings dialog's connection test. */
+export declare function probeWorker(workerUrl: string): Promise<{
+    ok: boolean;
+    detail: string;
+}>;
+/** Share liveness probe — the "session says shared but the link is dead"
+ * case (purged, TTL-expired, or deleted while the binding stayed in
+ * session metadata). GET /data answers 404 {status:"gone"} BEFORE the
+ * read-auth gate, so this is a credential-free existence check that
+ * works identically on the CF worker and the Bun server. Network errors
+ * return "unknown" — never auto-disable on unknown. */
+export declare function verifyShare(workerUrl: string, shareId: string): Promise<"live" | "gone" | "unknown">;
+/** Remove the binding entries for shares that no longer exist server-side
+ * (the auto-disable half of gone detection). Entries are deleted outright —
+ * not optedOut — so a later prompt in the session can create a fresh share. */
+export declare function clearGoneBindingEntries(host: ShareHostApi, root: string, servers: string[]): Promise<boolean>;
+export declare function normServerUrl(url: string): string;
+/** /health probe including the auth mode (public enrolls anyone). */
+export declare function probeAuthMode(workerUrl: string): Promise<{
+    ok: boolean;
+    mode?: "public" | "private";
+    detail: string;
+}>;
+export declare function enrollAtServer(workerUrl: string, code: string): Promise<{
+    ok: boolean;
+    token?: string;
+    userId?: string;
+    label?: string;
+    error?: string;
+}>;
+export declare function rotateAtServer(workerUrl: string, token: string): Promise<{
+    ok: boolean;
+    token?: string;
+    error?: string;
+}>;
+export declare function disconnectAtServer(workerUrl: string, token: string): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+export type AdminUser = {
+    id: string;
+    label: string;
+    createdAt: number;
+    frozen: boolean;
+    shares: number;
+    tokens: number;
+    tokensActive: number;
+};
+export type AdminToken = {
+    id: string;
+    userId: string;
+    label: string;
+    limits: Record<string, number>;
+    createdAt: number;
+    lastUsedAt: number;
+    expiresAt: number;
+    revoked: boolean;
+};
+export type AdminCode = {
+    id: string;
+    label: string;
+    activationsLeft: number;
+    used: number;
+    createdAt: number;
+    expiresAt: number;
+    disabled: boolean;
+};
+export type AdminShare = {
+    id: string;
+    createdAt: number;
+    sessionID?: string;
+    ownerId?: string | null;
+};
+/** Thin typed client for the worker's /api/admin surface. `token` must be
+ * the server's root CREATE_TOKEN (user osk_ tokens get 403). */
+export declare function adminClient(workerUrl: string, token: string): {
+    users: () => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            users: AdminUser[];
+        } | undefined;
+        error?: string;
+    }>;
+    createUser: (label: string) => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            userId: string;
+            label: string;
+        } | undefined;
+        error?: string;
+    }>;
+    freeze: (userId: string) => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            frozen: boolean;
+            shares: number;
+        } | undefined;
+        error?: string;
+    }>;
+    unfreeze: (userId: string) => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            frozen: boolean;
+            shares: number;
+        } | undefined;
+        error?: string;
+    }>;
+    deleteUser: (userId: string, mode: "freeze" | "delete") => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            mode: string;
+            shares: number;
+        } | undefined;
+        error?: string;
+    }>;
+    tokens: () => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            tokens: AdminToken[];
+        } | undefined;
+        error?: string;
+    }>;
+    mintToken: (userId: string, label?: string, limits?: Record<string, number>) => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            token: string;
+            id: string;
+        } | undefined;
+        error?: string;
+    }>;
+    revokeToken: (tokenId: string) => Promise<{
+        ok: boolean;
+        status: number;
+        data?: unknown;
+        error?: string;
+    }>;
+    codes: () => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            codes: AdminCode[];
+        } | undefined;
+        error?: string;
+    }>;
+    createCode: (label: string, activations: number) => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            code: string;
+            id: string;
+            activationsLeft: number;
+        } | undefined;
+        error?: string;
+    }>;
+    disableCode: (codeId: string) => Promise<{
+        ok: boolean;
+        status: number;
+        data?: unknown;
+        error?: string;
+    }>;
+    shares: () => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            shares: AdminShare[];
+        } | undefined;
+        error?: string;
+    }>;
+    deleteShare: (shareId: string) => Promise<{
+        ok: boolean;
+        status: number;
+        data?: unknown;
+        error?: string;
+    }>;
+    reassign: (shareId: string, userId: string) => Promise<{
+        ok: boolean;
+        status: number;
+        data?: unknown;
+        error?: string;
+    }>;
+    purge: () => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            removed: number;
+        } | undefined;
+        error?: string;
+    }>;
+    health: () => Promise<{
+        ok: boolean;
+        status: number;
+        data?: {
+            ok: boolean;
+            service: string;
+            policy: Record<string, unknown>;
+            auth: {
+                mode: string;
+            };
+        } | undefined;
+        error?: string;
+    }>;
+};
+/** Resolve the admin credential for a server: the entry's adminToken, the
+ * legacy createToken (when it points at this server), or prompt. */
+export declare function adminTokenFor(url: string, cfg?: ShareConfig): string;
+/** Waits for the server plugin to publish the binding URL (poll; robust on
+ * both hosts). Resolves the binding, or undefined on timeout. */
+export declare function waitForBinding(client: ClientApi | undefined, sid: string, timeoutMs?: number): Promise<SessionBinding | undefined>;
+export type FlowResult = {
+    ok: boolean;
+    message: string;
+    url?: string;
+    unconfigured?: boolean;
+};
+export declare function runShareFlow(host: ShareHostApi, sessionID: string | undefined): Promise<FlowResult>;
+/** Post-consent share: set the flag, wait for the URL, copy it. */
+export declare function confirmShare(host: ShareHostApi, rootSessionID: string): Promise<FlowResult>;
+export declare function runUnshareFlow(host: ShareHostApi, sessionID: string | undefined): Promise<FlowResult>;