@onesi/genesis 0.1.13 → 0.2.1

package/dist/hives-sse.js

@@ -0,0 +1,111 @@
+import { GenesisError } from './errors.js';
+const bound = (value, fallback, max, name) => {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1 || value > max) {
+        throw new GenesisError({ status: 0, type: 'invalid_request', message: `${name} must be an integer from 1 to ${max}.` });
+    }
+    return value;
+};
+function parse(lines) {
+    let event = 'message';
+    let id;
+    const data = [];
+    for (const line of lines) {
+        if (!line || line.startsWith(':'))
+            continue; // comments carry keepalives only
+        const colon = line.indexOf(':');
+        const field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        if (field === 'event')
+            event = value;
+        else if (field === 'id')
+            id = value;
+        else if (field === 'data')
+            data.push(value);
+    }
+    if (!data.length)
+        return undefined;
+    const text = data.join('\n');
+    let value = text;
+    try {
+        value = JSON.parse(text);
+    }
+    catch { /* keepalive text such as "ping" */ }
+    return { event, ...(id === undefined ? {} : { id }), data: value };
+}
+/**
+ * Read one bounded window of a Server-Sent Events response (for example
+ * `await genesis.raw('hives_stream_deployment_logs', {...})`) and close the connection.
+ * Never buffers the whole body: an SSE stream does not end on its own.
+ */
+export async function hivesSseWindow(response, options = {}) {
+    const maxEvents = bound(options.maxEvents, 100, 1000, 'maxEvents');
+    const seconds = bound(options.seconds, 10, 15, 'seconds');
+    const reader = response.body?.getReader();
+    const events = [];
+    if (!reader)
+        return { events, ended: 'closed' };
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let lines = [];
+    let ended;
+    const stop = (why) => { ended ??= why; void reader.cancel().catch(() => { }); };
+    const timer = setTimeout(() => stop('time'), seconds * 1000);
+    const abort = () => stop('aborted');
+    options.signal?.addEventListener('abort', abort, { once: true });
+    if (options.signal?.aborted)
+        abort();
+    try {
+        while (!ended) {
+            let chunk;
+            try {
+                chunk = await reader.read();
+            }
+            catch (error) {
+                if (ended)
+                    break;
+                throw error;
+            }
+            if (ended)
+                break;
+            if (chunk.done) {
+                buffer += decoder.decode();
+                ended = 'closed';
+            }
+            else
+                buffer += decoder.decode(chunk.value, { stream: true });
+            let index;
+            while ((index = buffer.search(/\r\n|\r|\n/)) >= 0) {
+                const line = buffer.slice(0, index);
+                buffer = buffer.slice(index + (buffer.startsWith('\r\n', index) ? 2 : 1));
+                if (line !== '') {
+                    lines.push(line);
+                    continue;
+                }
+                const event = parse(lines);
+                lines = [];
+                if (event)
+                    events.push(event);
+                if (events.length >= maxEvents) {
+                    stop('max_events');
+                    break;
+                }
+            }
+            if (ended === 'closed' && events.length < maxEvents) {
+                const tail = parse(buffer ? [...lines, buffer] : lines);
+                if (tail)
+                    events.push(tail);
+            }
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', abort);
+        if (ended !== 'closed')
+            void reader.cancel().catch(() => { });
+    }
+    return { events, ended: ended ?? 'closed' };
+}

package/dist/hives-topics.d.ts

@@ -1,5 +1,5 @@
 import type { GenesisClient } from './client.js';
-import { type HivesResourceOptions } from './hives-resources-transport.js';
+import { type HivesFundedWriteOptions, type HivesResourceOptions } from './hives-resources-transport.js';
 export interface HivesTopic {
     id: string;
     projectId: string;
@@ -46,6 +46,7 @@ export declare function hivesTopics(client: GenesisClient): {
             deleted: true;
         }>;
     };
-    /** Persists one delivery per subscription atomically. Never retried after an unknown outcome. */
-    publish(project: string, id: string, body: HivesTopicPublish, options?: HivesResourceOptions): Promise<HivesTopicPublication>;
+    /** Persists one delivery per subscription atomically. Never retried after an unknown outcome. Carries one
+     * Idempotency-Key (options.idempotencyKey, or a fresh one); reuse that key only to replay this publication. */
+    publish(project: string, id: string, body: HivesTopicPublish, options?: HivesFundedWriteOptions): Promise<HivesTopicPublication>;
 };

package/dist/hives-topics.js

@@ -1,5 +1,5 @@
 import { hivesQueueBody } from './hives-queues.js';
-import { HIVES_QUEUE_BYTES, hivesResourceCall, hivesResourceId, resourceError } from './hives-resources-transport.js';
+import { HIVES_QUEUE_BYTES, hivesFundedWriteHeaders, hivesResourceCall, hivesResourceId, resourceError } from './hives-resources-transport.js';
 const invalid = () => resourceError(0);
 const object = (v) => { if (!v || typeof v !== 'object' || Array.isArray(v))
     throw invalid(); return v; };
@@ -46,7 +46,7 @@ function publishInput(value) {
 }
 export function hivesTopics(client) {
     const ids = (project, id) => ({ project_id: hivesResourceId(project), ...(id === undefined ? {} : { topic_id: hivesResourceId(id) }) });
-    const call = (operation, input, options, status = 200) => hivesResourceCall(client, operation, input, options, 'json', 2 * 1024 * 1024, 20_000, status);
+    const call = (operation, input, options, status = 200, headers) => hivesResourceCall(client, operation, input, options, 'json', 2 * 1024 * 1024, 20_000, status, headers && { headers });
     const removed = (value) => { if (object(value).deleted !== true)
         throw invalid(); return { deleted: true }; };
     return {
@@ -64,10 +64,15 @@ export function hivesTopics(client) {
             async add(project, id, queueId, options) { const queue = hivesResourceId(queueId); return subscription(await call('hives_subscribe_native_topic', { ...ids(project, id), body: { queueId: queue } }, options, 201), project, id, queue); },
             async remove(project, id, subscriptionId, options) { return removed(await call('hives_unsubscribe_native_topic', { ...ids(project, id), subscription_id: hivesResourceId(subscriptionId) }, options)); },
         },
-        /** Persists one delivery per subscription atomically. Never retried after an unknown outcome. */
+        /** Persists one delivery per subscription atomically. Never retried after an unknown outcome. Carries one
+         * Idempotency-Key (options.idempotencyKey, or a fresh one); reuse that key only to replay this publication. */
         async publish(project, id, body, options) {
             publishInput(body);
-            const v = object(await call('hives_publish_native_topic', { ...ids(project, id), body }, options, 201));
+            const headers = hivesFundedWriteHeaders(options, 'hives_publish_native_topic');
+            const v = object(await call('hives_publish_native_topic', { ...ids(project, id), body }, options, 201, headers));
+            // A funded publication answers with its settled operation receipt, which carries the same publication fields.
+            if (v.object !== undefined && (v.object !== 'pubsub_publish_operation' || v.state !== 'settled'))
+                throw invalid();
             if (!Array.isArray(v.deliveries) || v.deliveries.length > 32)
                 throw invalid();
             const deliveries = v.deliveries.map(raw => { const d = object(raw); return { subscription_id: nativeId(d.subscription_id, 'sub'), queue_id: hivesResourceId(d.queue_id), message_id: hivesResourceId(d.message_id) }; });

package/dist/iam-directory.d.ts

@@ -0,0 +1,8 @@
+export declare const iamDirectoryOperations: readonly string[];
+export declare const isIamDirectoryOperation: (operationId: string) => boolean;
+/**
+ * The actionable form of a directory refusal; any other error is returned unchanged. The gateway, not the client, exchanges
+ * the One account session for an organization context at Auth and forwards the short-lived child to IAM. The client sends
+ * one request, never changes a session or its selected context, and only explains what came back.
+ */
+export declare function iamDirectoryFailure(e: unknown, org: string, operationId: string): unknown;

package/dist/iam-directory.js

@@ -0,0 +1,23 @@
+import { GenesisError, errorCatalog } from './errors.js';
+/** The IAM v4 organization directory: projects and workspaces at /v1/iam/orgs/{org_id}/... */
+const READS = ['iam_listProjects', 'iam_getProject', 'iam_listWorkspaces', 'iam_getWorkspace'];
+const WRITES = ['iam_createProject', 'iam_updateProject', 'iam_deleteProject', 'iam_createWorkspace', 'iam_updateWorkspace', 'iam_deleteWorkspace'];
+export const iamDirectoryOperations = [...READS, ...WRITES];
+export const isIamDirectoryOperation = (operationId) => iamDirectoryOperations.includes(operationId);
+const codeOf = (e) => errorCatalog(e).code?.toUpperCase();
+/**
+ * The actionable form of a directory refusal; any other error is returned unchanged. The gateway, not the client, exchanges
+ * the One account session for an organization context at Auth and forwards the short-lived child to IAM. The client sends
+ * one request, never changes a session or its selected context, and only explains what came back.
+ */
+export function iamDirectoryFailure(e, org, operationId) {
+    if (!(e instanceof GenesisError))
+        return e;
+    const keep = (message) => new GenesisError({ status: e.status, type: e.type, code: e.code, requestId: e.requestId, operationId, body: e.body, message });
+    const code = codeOf(e);
+    if (code === 'TENANT_REQUIRED')
+        return keep(`IAM sees no organization on your One account session for ${org}. Use the Console to manage projects and workspaces for now.`);
+    if (WRITES.includes(operationId) && code === 'SCOPE_MISSING' && errorCatalog(e).required_scope === 'iam:write')
+        return keep(`This credential cannot change projects and workspaces in ${org}: a login needs the organization owner or manager role in IAM, and an API key needs iam:write. Use the Console.`);
+    return e;
+}

package/dist/iam.d.ts

@@ -0,0 +1,397 @@
+import type { GenesisClient } from './client.js';
+import type { OperationId } from './generated/operations.js';
+import type { OperationInput } from './types.js';
+type Body<K extends OperationId> = OperationInput<K> extends {
+    body?: infer B;
+} ? NonNullable<B> : never;
+type Query<K extends OperationId> = Omit<OperationInput<K>, 'body'>;
+/**
+ * IAM v4 tenant operations at /v1/iam/... (iam.l1fe.ai). Use a One account login or an organization API key with iam:read
+ * (reads) or iam:write (changes). The gateway exchanges either at Auth for a short-lived IAM token and forwards only that;
+ * IAM decides authority (owner or manager for most changes). `org_id` must be your own organization.
+ *
+ * Inviting members, changing member roles, removing members, Mind API keys and enterprise settings are not here: they stay
+ * with a person in the Console. Projects and workspaces are `genesis.projects` and `genesis.workspaces`.
+ */
+export declare function iamModule(client: GenesisClient): {
+    orgs: {
+        list: (query?: Query<"iam_listOrgs">) => Promise<{
+            items: import("./index.js").components["schemas"]["Iam.Organization"][];
+            next_cursor?: string | null;
+        }>;
+        get: (org_id: string) => Promise<{
+            id: string;
+            name: string;
+            slug: string;
+            owner_human_principal_id?: string;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            created_at: number;
+            role?: string;
+        }>;
+        update: (org_id: string, body: Body<"iam_updateOrg">) => Promise<{
+            id: string;
+            name: string;
+            slug: string;
+            owner_human_principal_id?: string;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            created_at: number;
+            role?: string;
+        }>;
+        members: (org_id: string, query?: Omit<Query<"iam_listMembers">, "org_id">) => Promise<{
+            items: import("./index.js").components["schemas"]["Iam.Member"][];
+            total?: number;
+            nextCursor?: string | null;
+            complete?: boolean;
+            canManageMembers?: boolean;
+        }>;
+        entitlements: (org_id: string, environment_id?: "live" | "sandbox") => Promise<{
+            items: import("./index.js").components["schemas"]["Iam.Entitlement"][];
+            next_cursor?: string | null;
+            snapshotVersion?: unknown;
+            snapshotGeneratedAt?: unknown;
+            snapshotValidUntil?: unknown;
+            environmentId?: string;
+        }>;
+    };
+    fleets: {
+        list: (org_id: string) => Promise<{
+            items: import("./index.js").components["schemas"]["Iam.Fleet"][];
+            next_cursor?: string | null;
+        }>;
+        get: (org_id: string, fleet_id: string) => Promise<{
+            id: string;
+            organizationId: string;
+            projectId?: string;
+            workspaceId?: string;
+            name: string;
+            slug: string;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            createdAt: number;
+            updatedAt: number;
+        }>;
+        /** Reuse the same idempotencyKey to replay an uncertain create instead of making a second fleet. */
+        create: (org_id: string, body: Body<"iam_createFleet">, idempotencyKey: string) => Promise<{
+            id: string;
+            organizationId: string;
+            projectId?: string;
+            workspaceId?: string;
+            name: string;
+            slug: string;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            createdAt: number;
+            updatedAt: number;
+        }>;
+        update: (org_id: string, fleet_id: string, body: Body<"iam_updateFleet">) => Promise<{
+            id: string;
+            organizationId: string;
+            projectId?: string;
+            workspaceId?: string;
+            name: string;
+            slug: string;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            createdAt: number;
+            updatedAt: number;
+        }>;
+        /** Permanent; IAM refuses while grants reference the fleet. */
+        delete: (org_id: string, fleet_id: string) => Promise<void>;
+    };
+    agents: {
+        list: (org_id: string) => Promise<{
+            items: import("./index.js").components["schemas"]["Iam.Agent"][];
+            next_cursor?: string | null;
+            agents?: import("./index.js").components["schemas"]["Iam.Agent"][];
+        }>;
+        get: (org_id: string, agent_did: string) => Promise<{
+            agent: import("./index.js").components["schemas"]["Iam.Agent"];
+        }>;
+        /** Without `publicKey` IAM generates a key pair and returns `privateKey` once. */
+        create: (org_id: string, body: Body<"iam_createAgent">) => Promise<{
+            agent: import("./index.js").components["schemas"]["Iam.Agent"];
+            did: string;
+            publicKey?: string | null;
+            privateKey?: string | null;
+        }>;
+        /** Revokes the agent (status `revoked`); the record stays. */
+        delete: (org_id: string, agent_did: string) => Promise<{
+            agent: import("./index.js").components["schemas"]["Iam.Agent"];
+        }>;
+        suspend: (org_id: string, agent_did: string) => Promise<{
+            agent: import("./index.js").components["schemas"]["Iam.Agent"];
+        }>;
+        resume: (org_id: string, agent_did: string) => Promise<{
+            agent: import("./index.js").components["schemas"]["Iam.Agent"];
+        }>;
+        rotate: (org_id: string, agent_did: string, body?: Body<"iam_rotateAgentKey">) => Promise<{
+            did: string;
+            publicKey?: string | null;
+            privateKey?: string | null;
+        }>;
+        acts: {
+            list: (org_id: string, agent_did: string) => Promise<{
+                acts: {
+                    [key: string]: unknown;
+                }[];
+            }>;
+            issue: (org_id: string, agent_did: string, body: Body<"iam_issueAgentAct">) => Promise<{
+                id: string;
+                act: string;
+                scopes: string[];
+                issuedAt: string;
+                expiresAt: string;
+                subjectDid: string;
+            }>;
+        };
+        publication: (org_id: string, agent_id: string) => Promise<{
+            agentId: string;
+            state: "private" | "published" | "withdrawn";
+            version: number;
+        }>;
+        orbitMsgsGrant: (org_id: string, agent_id: string) => Promise<{
+            schemaVersion?: number;
+            requestId?: string;
+            agentId: string;
+            organizationId: string;
+            profile?: string;
+            ownerGeneration?: number;
+            grant?: {
+                grantId?: string;
+                grantVersion?: number;
+                actions?: string[];
+                expiresAtMs?: number;
+                status?: "active" | "expired" | "revoked";
+            } | null;
+        }>;
+        /** A published agent's public card (anonymous). */
+        publicCard: (agent_id: string) => Promise<{
+            schemaVersion?: number;
+            principalId: string;
+            kind: string;
+            publicationVersion?: number;
+            canonicalAgentDid?: string;
+            handle?: string | null;
+            handleStatus?: string;
+            contact?: {
+                [key: string]: unknown;
+            };
+            operatingCompany?: Record<string, never> | null;
+        }>;
+        /** Agents enrolled for a Mind with a currently valid credential. */
+        forMind: (org_id: string, mind_id: string) => Promise<{
+            items: {
+                agent: import("./index.js").components["schemas"]["Iam.Agent"];
+                mindId: string;
+                scopes?: string[];
+                sharedNamespaces?: string[];
+                credentialExpiresAt?: number;
+            }[];
+        }>;
+        enrollmentGrants: (org_id: string) => Promise<{
+            items: import("./index.js").components["schemas"]["Iam.AgentEnrollmentGrant"][];
+        }>;
+        /**
+         * Enroll an agent under an agent enrollment grant. Only the grant's enrollment key (`mek_...`) is sent, as the bearer;
+         * this client's own Genesis credential is not. The credential secret in the answer is returned once.
+         */
+        enroll: (enrollmentKey: string, body: Body<"iam_enrollAgent">) => Promise<{
+            agent: {
+                id: string;
+                did: string;
+                displayName?: string;
+                status?: string;
+                organizationId: string;
+                projectId?: string;
+            };
+            created: boolean;
+            credential: {
+                id: string;
+                secret: string;
+                mindId?: string;
+                scopes?: string[];
+                sharedNamespaces?: string[];
+                expiresAt?: number;
+            };
+        }>;
+    };
+    roles: {
+        list: (org_id: string) => Promise<{
+            items: import("./index.js").components["schemas"]["Iam.Role"][];
+            next_cursor?: string | null;
+        }>;
+        get: (org_id: string, role_id: string) => Promise<{
+            id: string;
+            organization_id?: string;
+            name: string;
+            description?: string;
+            permissions: string[];
+            metadata?: {
+                [key: string]: unknown;
+            };
+        }>;
+        create: (org_id: string, body: Body<"iam_createRole">) => Promise<{
+            id: string;
+            organization_id?: string;
+            name: string;
+            description?: string;
+            permissions: string[];
+            metadata?: {
+                [key: string]: unknown;
+            };
+        }>;
+        update: (org_id: string, role_id: string, body: Body<"iam_updateRole">) => Promise<{
+            id: string;
+            organization_id?: string;
+            name: string;
+            description?: string;
+            permissions: string[];
+            metadata?: {
+                [key: string]: unknown;
+            };
+        }>;
+        delete: (org_id: string, role_id: string) => Promise<void>;
+    };
+    grants: {
+        list: (query?: Query<"iam_listGrants">) => Promise<{
+            items: import("./index.js").components["schemas"]["Iam.Grant"][];
+            next_cursor?: string | null;
+        }>;
+        get: (grant_id: string) => Promise<{
+            id: string;
+            principal_id: string;
+            organization_id: string;
+            project_id?: string;
+            platform_id?: string;
+            workspace_id?: string;
+            environmentId?: "live" | "sandbox";
+            role_ids: string[];
+            permissions?: string[];
+            expires_at?: number;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            created_at: number;
+        }>;
+        /** `organization_id` must be your organization. With an idempotencyKey a retry returns the original grant. */
+        create: (body: Body<"iam_createGrant">, idempotencyKey?: string) => Promise<{
+            id: string;
+            principal_id: string;
+            organization_id: string;
+            project_id?: string;
+            platform_id?: string;
+            workspace_id?: string;
+            environmentId?: "live" | "sandbox";
+            role_ids: string[];
+            permissions?: string[];
+            expires_at?: number;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            created_at: number;
+        }>;
+        update: (grant_id: string, body: Body<"iam_updateGrant">) => Promise<{
+            id: string;
+            principal_id: string;
+            organization_id: string;
+            project_id?: string;
+            platform_id?: string;
+            workspace_id?: string;
+            environmentId?: "live" | "sandbox";
+            role_ids: string[];
+            permissions?: string[];
+            expires_at?: number;
+            metadata?: {
+                [key: string]: unknown;
+            };
+            created_at: number;
+        }>;
+        delete: (grant_id: string) => Promise<void>;
+    };
+    capabilities: {
+        get: (capability_id: string) => Promise<{
+            id: string;
+            issuer_principal_id: string;
+            subject_principal_id: string;
+            organization_id: string;
+            permissions: string[];
+            constraints: import("./index.js").components["schemas"]["Iam.CapabilityConstraints"];
+            created_at: number;
+            revoked_at?: number;
+            revoke_reason?: string;
+        }>;
+        /** You are always the issuer; `organization_id` must be your organization. */
+        create: (body: Body<"iam_createCapability">, idempotencyKey?: string) => Promise<{
+            id: string;
+            issuer_principal_id: string;
+            subject_principal_id: string;
+            organization_id: string;
+            permissions: string[];
+            constraints: import("./index.js").components["schemas"]["Iam.CapabilityConstraints"];
+            created_at: number;
+            revoked_at?: number;
+            revoke_reason?: string;
+        }>;
+        update: (capability_id: string, body: Body<"iam_updateCapability">) => Promise<{
+            id: string;
+            issuer_principal_id: string;
+            subject_principal_id: string;
+            organization_id: string;
+            permissions: string[];
+            constraints: import("./index.js").components["schemas"]["Iam.CapabilityConstraints"];
+            created_at: number;
+            revoked_at?: number;
+            revoke_reason?: string;
+        }>;
+        /** Revoke (issuer only), with an optional recorded reason. */
+        delete: (capability_id: string, reason?: string) => Promise<void>;
+        verify: (body: Body<"iam_verifyCapability">) => Promise<{
+            valid: boolean;
+            grant?: import("./index.js").components["schemas"]["Iam.Capability"];
+            reason_invalid?: "expired" | "revoked" | "scope_mismatch" | "tenant_mismatch" | "not_found";
+        }>;
+    };
+    platforms: () => Promise<{
+        items: import("./index.js").components["schemas"]["Iam.Platform"][];
+        next_cursor?: string | null;
+    }>;
+    tenantContext: () => Promise<{
+        organizationId: string;
+        projectId: string;
+        platformId: string;
+        workspaceId?: string;
+        fleetId?: string;
+        organizationName?: string;
+        environmentId?: string;
+    }>;
+    checkPermission: (body: Body<"iam_checkPermission">) => Promise<{
+        allowed: boolean;
+        evaluated_at?: number;
+        via?: string;
+        environmentId?: string;
+    }>;
+    requirePermission: (body: Body<"iam_requirePermission">) => Promise<{
+        allowed: boolean;
+        evaluated_at?: number;
+        via?: string;
+        environmentId?: string;
+    }>;
+    checkEntitlement: (body: Body<"iam_checkEntitlement">) => Promise<{
+        key: string;
+        organization_id: string;
+        enabled: boolean;
+        quota?: number | null;
+        remaining?: number | null;
+        evaluated_at?: number;
+        source?: string;
+        environmentId?: string;
+    }>;
+};
+export {};