@cerebro-labs/agentnava-sdk 0.26.0

package/end-user.d.ts

@@ -0,0 +1,159 @@
+import { Connection } from './connection.ts';
+import { Secret } from './secret.ts';
+import { Conversation } from './conversation.ts';
+import type { Http } from './http.ts';
+/**
+ * One of YOUR end users, as this platform sees them.
+ *
+ * WHY THE NAME IS `EndUser` AND NOT `User`. There are two populations of people
+ * in this product, and calling both of them "user" was a bug waiting to be
+ * written:
+ *
+ * | | workspace member | END USER |
+ * |---|---|---|
+ * | who | your colleague, on a seat | the person your application serves |
+ * | signs in to this platform | yes | NEVER |
+ * | who issues the id | we do | YOUR database |
+ * | do we authenticate it | yes | no, deliberately |
+ * | in this SDK | `ws.members()` | `ws.endUser(id)` |
+ *
+ * They were both spelled `userId`, so `ws.members()` handed you an id that
+ * `agent.start()` would accept without complaint and label a conversation with
+ * a teammate's internal platform id. It could never have errored, because an
+ * end-user id is never checked against anything. The two names now make that
+ * call impossible to write by accident.
+ *
+ * NOT `Customer`, which was tried and reverted. Two reasons. "Customer" already
+ * means the party that BUYS this platform, in our own strategy documents and in
+ * `subscriptions.stripe_customer_id`, so the word points the other way. And it
+ * is wrong for the common case: an enterprise deploying an internal workflow
+ * agent serves its own EMPLOYEES, who are not anybody's customers.
+ *
+ * WHY THIS OBJECT EXISTS. You are building an application for many people.
+ * Ananya has her own Gmail, her own conversations and her own history, and so
+ * do the other ten thousand. Every call you make is on behalf of one of them.
+ *
+ * Without this, the person is an argument: `endUserId` threaded through
+ * `connections.create`, `secrets.create`, `conversations` and `start`, and
+ * forgotten in exactly one of them one day. With it, you say who once and the
+ * rest follows:
+ *
+ * ```ts
+ * const ananya = ws.endUser(row.userId);       // no request
+ *
+ * const gmail = await ananya.connections.create({ provider: 'gmail' });
+ * showToUser(gmail.url);
+ * await gmail.waitUntilConnected();
+ *
+ * const conversation = await agent.start({ endUserId: ananya.id });
+ * await conversation.attach(gmail);            // EXPLICIT. Nothing is implied.
+ * await conversation.ask('what did I miss this morning?');
+ *
+ * await ananya.conversations();                // everything of hers, any agent
+ * ```
+ *
+ * NAMING AN END USER GRANTS NOTHING. `start({ endUserId })` labels the
+ * conversation so it can be listed back to them; it does not hand the agent
+ * their accounts. The `attach` is the grant, and it is a line you can see.
+ *
+ * An earlier version resolved a person's credentials automatically from that
+ * label. It was wrong even when it picked correctly: reading the code told you
+ * nothing about what the agent could reach, and one mistyped id silently swapped
+ * whose mailbox a turn read.
+ *
+ * THE ID IS YOURS. A row id from your database, opaque to us, and we never
+ * authenticate it. We are not an identity provider and do not want to be. It
+ * also means passing the wrong one hands that person somebody else's mailbox,
+ * which is a sharper consequence than the same mistake has for a chat list.
+ *
+ * Holding one makes NO request.
+ */
+export declare class EndUser {
+    #private;
+    readonly id: string;
+    constructor(http: Http, id: string);
+    /**
+     * This person's own third-party accounts.
+     *
+     * Connected ONCE, in their browser. After that the account is theirs and
+     * stays theirs: you attach it to whichever conversations should use it,
+     * rather than sending them through a sign-in again per thread. That is the
+     * saving. The attach is not.
+     *
+     * Listing here is the CALLER'S view, for showing someone what they have
+     * connected and for revoking it when they leave. It is not what a turn
+     * consults: a turn sees only what was attached to it.
+     */
+    readonly connections: {
+        /** Begin connecting. Returns a `Connection` carrying the url to send
+         *  them to; `waitUntilConnected()` tells you when they are done. */
+        create: (input: {
+            provider: string;
+        }) => Promise<Connection>;
+        /** Theirs alone. The shared workspace and agent accounts are not here;
+         *  `ws.connections.list()` is the view that shows those. */
+        list: () => Promise<Connection[]>;
+    };
+    /**
+     * Credentials that belong to THIS PERSON: their API key for a system you
+     * integrate with, their token for a service only they have an account on.
+     *
+     * THIS WAS ABSENT UNTIL THERE WAS A WAY TO USE IT. A credential reaches a
+     * turn only by being ATTACHED. A connection could be, by id; a secret could
+     * not, because binding one took its VALUE, and you do not hold the value of a
+     * secret the platform stored for you. So a per-person secret would have been
+     * a surface that accepted writes, listed them back, and was read by nothing.
+     * It was left out rather than shipped looking like a feature.
+     *
+     * `sessionBindings.secretIds` is what closed it, and attaching is still an
+     * explicit line:
+     *
+     * ```ts
+     * const ananya = ws.endUser(row.userId);
+     * const key = await ananya.secrets.create({ name: 'ZENDESK_TOKEN', value: token });
+     *
+     * const conversation = await agent.start({ endUserId: ananya.id });
+     * await conversation.attach(key);            // EXPLICIT. Nothing is implied.
+     * ```
+     *
+     * TWO THINGS THE PLATFORM ENFORCES, neither of which you can turn off:
+     * the agent must DECLARE that secret name at session scope, so attaching by
+     * id is not a way around the allowlist; and a secret belonging to one end
+     * user can only be attached to a conversation launched for that same person,
+     * so one mistyped id cannot hand Ananya's key to somebody else's turn.
+     */
+    readonly secrets: {
+        /** Store a credential for this person. The value is encrypted on arrival
+         *  and never handed back, which is why attaching uses the id. */
+        create: (input: {
+            name: string;
+            value: string;
+            description?: string;
+            agentId?: string;
+        }) => Promise<Secret>;
+        /** This person's secrets, values excluded. The workspace's own are not in
+         *  here: `ws.secrets.list()` answers that. */
+        list: () => Promise<Secret[]>;
+    };
+    /**
+     * Everything this person has said, ACROSS EVERY AGENT, newest first.
+     *
+     * `agent.conversations({ endUser })` answers the narrower question, one agent
+     * at a time. This is the one an application renders as "your chats", and it
+     * is the only listing in this SDK with a real cursor: pass `before` from the
+     * previous page to keep going, rather than being capped at 200.
+     */
+    conversations(options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<Conversation[]>;
+    /**
+     * Cut this person off.
+     *
+     * Revokes every account they connected, so every conversation of theirs
+     * stops acting as them from the next turn. What off-boarding calls, and the
+     * reason it is one call rather than a loop the caller has to remember to
+     * write.
+     */
+    revokeConnections(): Promise<void>;
+}

package/end-user.js

@@ -0,0 +1,209 @@
+// One of YOUR end users: a person your application serves, who never signs in here.
+import { Connection } from "./connection.js";
+import { toConnectionStatus } from "./connection-status.js";
+import { Secret } from "./secret.js";
+import { Conversation } from "./conversation.js";
+/**
+ * One of YOUR end users, as this platform sees them.
+ *
+ * WHY THE NAME IS `EndUser` AND NOT `User`. There are two populations of people
+ * in this product, and calling both of them "user" was a bug waiting to be
+ * written:
+ *
+ * | | workspace member | END USER |
+ * |---|---|---|
+ * | who | your colleague, on a seat | the person your application serves |
+ * | signs in to this platform | yes | NEVER |
+ * | who issues the id | we do | YOUR database |
+ * | do we authenticate it | yes | no, deliberately |
+ * | in this SDK | `ws.members()` | `ws.endUser(id)` |
+ *
+ * They were both spelled `userId`, so `ws.members()` handed you an id that
+ * `agent.start()` would accept without complaint and label a conversation with
+ * a teammate's internal platform id. It could never have errored, because an
+ * end-user id is never checked against anything. The two names now make that
+ * call impossible to write by accident.
+ *
+ * NOT `Customer`, which was tried and reverted. Two reasons. "Customer" already
+ * means the party that BUYS this platform, in our own strategy documents and in
+ * `subscriptions.stripe_customer_id`, so the word points the other way. And it
+ * is wrong for the common case: an enterprise deploying an internal workflow
+ * agent serves its own EMPLOYEES, who are not anybody's customers.
+ *
+ * WHY THIS OBJECT EXISTS. You are building an application for many people.
+ * Ananya has her own Gmail, her own conversations and her own history, and so
+ * do the other ten thousand. Every call you make is on behalf of one of them.
+ *
+ * Without this, the person is an argument: `endUserId` threaded through
+ * `connections.create`, `secrets.create`, `conversations` and `start`, and
+ * forgotten in exactly one of them one day. With it, you say who once and the
+ * rest follows:
+ *
+ * ```ts
+ * const ananya = ws.endUser(row.userId);       // no request
+ *
+ * const gmail = await ananya.connections.create({ provider: 'gmail' });
+ * showToUser(gmail.url);
+ * await gmail.waitUntilConnected();
+ *
+ * const conversation = await agent.start({ endUserId: ananya.id });
+ * await conversation.attach(gmail);            // EXPLICIT. Nothing is implied.
+ * await conversation.ask('what did I miss this morning?');
+ *
+ * await ananya.conversations();                // everything of hers, any agent
+ * ```
+ *
+ * NAMING AN END USER GRANTS NOTHING. `start({ endUserId })` labels the
+ * conversation so it can be listed back to them; it does not hand the agent
+ * their accounts. The `attach` is the grant, and it is a line you can see.
+ *
+ * An earlier version resolved a person's credentials automatically from that
+ * label. It was wrong even when it picked correctly: reading the code told you
+ * nothing about what the agent could reach, and one mistyped id silently swapped
+ * whose mailbox a turn read.
+ *
+ * THE ID IS YOURS. A row id from your database, opaque to us, and we never
+ * authenticate it. We are not an identity provider and do not want to be. It
+ * also means passing the wrong one hands that person somebody else's mailbox,
+ * which is a sharper consequence than the same mistake has for a chat list.
+ *
+ * Holding one makes NO request.
+ */
+export class EndUser {
+    id;
+    #http;
+    constructor(http, id) {
+        this.#http = http;
+        this.id = id;
+    }
+    /**
+     * This person's own third-party accounts.
+     *
+     * Connected ONCE, in their browser. After that the account is theirs and
+     * stays theirs: you attach it to whichever conversations should use it,
+     * rather than sending them through a sign-in again per thread. That is the
+     * saving. The attach is not.
+     *
+     * Listing here is the CALLER'S view, for showing someone what they have
+     * connected and for revoking it when they leave. It is not what a turn
+     * consults: a turn sees only what was attached to it.
+     */
+    connections = {
+        /** Begin connecting. Returns a `Connection` carrying the url to send
+         *  them to; `waitUntilConnected()` tells you when they are done. */
+        create: async (input) => {
+            const res = await this.#http.post('/v1/connections/connect', { provider: input.provider, endUserId: this.id });
+            return new Connection(this.#http, res.connectionId, 
+            // NOT `as never`. That cast was here to let `scope: 'user'` through,
+            // a value outside ConnectionStatus's own type, and it disabled
+            // checking on every other field at the same time.
+            {
+                id: res.connectionId,
+                provider: input.provider,
+                connected: false,
+                declared: true,
+                required: false,
+                endUserId: this.id,
+            }, res.authUrl);
+        },
+        /** Theirs alone. The shared workspace and agent accounts are not here;
+         *  `ws.connections.list()` is the view that shows those. */
+        list: async () => {
+            // WireConnection, not ConnectionStatus. The endpoint sends the wire
+            // shape, and typing it as the SDK shape is what hid the whole bug:
+            // `connected` is never sent, so every account here reported
+            // `connected === undefined` while type-checking as a boolean.
+            const res = await this.#http.get('/v1/connections', {
+                endUserId: this.id,
+            });
+            return (res.connections ?? [])
+                .filter((c) => c.id)
+                .map((c) => new Connection(this.#http, c.id, toConnectionStatus(c)));
+        },
+    };
+    /**
+     * Credentials that belong to THIS PERSON: their API key for a system you
+     * integrate with, their token for a service only they have an account on.
+     *
+     * THIS WAS ABSENT UNTIL THERE WAS A WAY TO USE IT. A credential reaches a
+     * turn only by being ATTACHED. A connection could be, by id; a secret could
+     * not, because binding one took its VALUE, and you do not hold the value of a
+     * secret the platform stored for you. So a per-person secret would have been
+     * a surface that accepted writes, listed them back, and was read by nothing.
+     * It was left out rather than shipped looking like a feature.
+     *
+     * `sessionBindings.secretIds` is what closed it, and attaching is still an
+     * explicit line:
+     *
+     * ```ts
+     * const ananya = ws.endUser(row.userId);
+     * const key = await ananya.secrets.create({ name: 'ZENDESK_TOKEN', value: token });
+     *
+     * const conversation = await agent.start({ endUserId: ananya.id });
+     * await conversation.attach(key);            // EXPLICIT. Nothing is implied.
+     * ```
+     *
+     * TWO THINGS THE PLATFORM ENFORCES, neither of which you can turn off:
+     * the agent must DECLARE that secret name at session scope, so attaching by
+     * id is not a way around the allowlist; and a secret belonging to one end
+     * user can only be attached to a conversation launched for that same person,
+     * so one mistyped id cannot hand Ananya's key to somebody else's turn.
+     */
+    secrets = {
+        /** Store a credential for this person. The value is encrypted on arrival
+         *  and never handed back, which is why attaching uses the id. */
+        create: async (input) => {
+            // FIELDS PICKED, never the input object forwarded. Removing a field
+            // from a type does not stop a JavaScript caller sending it, and
+            // forwarding wholesale is how `endUserId` kept reaching the API after
+            // it had supposedly been removed.
+            const res = await this.#http.post('/v1/secrets', {
+                name: input.name,
+                value: input.value,
+                endUserId: this.id,
+                ...(input.description !== undefined && { description: input.description }),
+                ...(input.agentId !== undefined && { agentId: input.agentId }),
+            });
+            const meta = res.secret ?? res;
+            return new Secret(this.#http, meta.id, meta);
+        },
+        /** This person's secrets, values excluded. The workspace's own are not in
+         *  here: `ws.secrets.list()` answers that. */
+        list: async () => {
+            const res = await this.#http.get('/v1/secrets', {
+                end_user_id: this.id,
+            });
+            return (res.secrets ?? []).map((m) => new Secret(this.#http, m.id, m));
+        },
+    };
+    /**
+     * Everything this person has said, ACROSS EVERY AGENT, newest first.
+     *
+     * `agent.conversations({ endUser })` answers the narrower question, one agent
+     * at a time. This is the one an application renders as "your chats", and it
+     * is the only listing in this SDK with a real cursor: pass `before` from the
+     * previous page to keep going, rather than being capped at 200.
+     */
+    async conversations(options = {}) {
+        const res = await this.#http.get('/v1/conversations', {
+            end_user_id: this.id,
+            ...(options.limit !== undefined && { limit: options.limit }),
+            ...(options.before && { before: options.before }),
+        });
+        return (res.conversations ?? []).map((c) => new Conversation(this.#http, c.id, c));
+    }
+    /**
+     * Cut this person off.
+     *
+     * Revokes every account they connected, so every conversation of theirs
+     * stops acting as them from the next turn. What off-boarding calls, and the
+     * reason it is one call rather than a loop the caller has to remember to
+     * write.
+     */
+    async revokeConnections() {
+        for (const connection of await this.connections.list()) {
+            await connection.revoke();
+        }
+    }
+}
+//# sourceMappingURL=end-user.js.map

package/end-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"end-user.js","sourceRoot":"","sources":["../src/end-user.ts"],"names":[],"mappings":"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","sourcesContent":["// One of YOUR end users: a person your application serves, who never signs in here.\n\nimport { Connection } from './connection.ts';\nimport { toConnectionStatus, type WireConnection } from './connection-status.ts';\nimport { Secret } from './secret.ts';\nimport { Conversation } from './conversation.ts';\nimport type { Http } from './http.ts';\nimport type { AgentConversationData, ConnectionStatus, SecretMeta } from './types.ts';\n\n/**\n * One of YOUR end users, as this platform sees them.\n *\n * WHY THE NAME IS `EndUser` AND NOT `User`. There are two populations of people\n * in this product, and calling both of them \"user\" was a bug waiting to be\n * written:\n *\n * | | workspace member | END USER |\n * |---|---|---|\n * | who | your colleague, on a seat | the person your application serves |\n * | signs in to this platform | yes | NEVER |\n * | who issues the id | we do | YOUR database |\n * | do we authenticate it | yes | no, deliberately |\n * | in this SDK | `ws.members()` | `ws.endUser(id)` |\n *\n * They were both spelled `userId`, so `ws.members()` handed you an id that\n * `agent.start()` would accept without complaint and label a conversation with\n * a teammate's internal platform id. It could never have errored, because an\n * end-user id is never checked against anything. The two names now make that\n * call impossible to write by accident.\n *\n * NOT `Customer`, which was tried and reverted. Two reasons. \"Customer\" already\n * means the party that BUYS this platform, in our own strategy documents and in\n * `subscriptions.stripe_customer_id`, so the word points the other way. And it\n * is wrong for the common case: an enterprise deploying an internal workflow\n * agent serves its own EMPLOYEES, who are not anybody's customers.\n *\n * WHY THIS OBJECT EXISTS. You are building an application for many people.\n * Ananya has her own Gmail, her own conversations and her own history, and so\n * do the other ten thousand. Every call you make is on behalf of one of them.\n *\n * Without this, the person is an argument: `endUserId` threaded through\n * `connections.create`, `secrets.create`, `conversations` and `start`, and\n * forgotten in exactly one of them one day. With it, you say who once and the\n * rest follows:\n *\n * ```ts\n * const ananya = ws.endUser(row.userId);       // no request\n *\n * const gmail = await ananya.connections.create({ provider: 'gmail' });\n * showToUser(gmail.url);\n * await gmail.waitUntilConnected();\n *\n * const conversation = await agent.start({ endUserId: ananya.id });\n * await conversation.attach(gmail);            // EXPLICIT. Nothing is implied.\n * await conversation.ask('what did I miss this morning?');\n *\n * await ananya.conversations();                // everything of hers, any agent\n * ```\n *\n * NAMING AN END USER GRANTS NOTHING. `start({ endUserId })` labels the\n * conversation so it can be listed back to them; it does not hand the agent\n * their accounts. The `attach` is the grant, and it is a line you can see.\n *\n * An earlier version resolved a person's credentials automatically from that\n * label. It was wrong even when it picked correctly: reading the code told you\n * nothing about what the agent could reach, and one mistyped id silently swapped\n * whose mailbox a turn read.\n *\n * THE ID IS YOURS. A row id from your database, opaque to us, and we never\n * authenticate it. We are not an identity provider and do not want to be. It\n * also means passing the wrong one hands that person somebody else's mailbox,\n * which is a sharper consequence than the same mistake has for a chat list.\n *\n * Holding one makes NO request.\n */\nexport class EndUser {\n\treadonly id: string;\n\treadonly #http: Http;\n\n\tconstructor(http: Http, id: string) {\n\t\tthis.#http = http;\n\t\tthis.id = id;\n\t}\n\n\t/**\n\t * This person's own third-party accounts.\n\t *\n\t * Connected ONCE, in their browser. After that the account is theirs and\n\t * stays theirs: you attach it to whichever conversations should use it,\n\t * rather than sending them through a sign-in again per thread. That is the\n\t * saving. The attach is not.\n\t *\n\t * Listing here is the CALLER'S view, for showing someone what they have\n\t * connected and for revoking it when they leave. It is not what a turn\n\t * consults: a turn sees only what was attached to it.\n\t */\n\treadonly connections = {\n\t\t/** Begin connecting. Returns a `Connection` carrying the url to send\n\t\t *  them to; `waitUntilConnected()` tells you when they are done. */\n\t\tcreate: async (input: { provider: string }): Promise<Connection> => {\n\t\t\tconst res = await this.#http.post<{ authUrl: string; connectionId: string }>(\n\t\t\t\t'/v1/connections/connect',\n\t\t\t\t{ provider: input.provider, endUserId: this.id },\n\t\t\t);\n\t\t\treturn new Connection(\n\t\t\t\tthis.#http,\n\t\t\t\tres.connectionId,\n\t\t\t\t// NOT `as never`. That cast was here to let `scope: 'user'` through,\n\t\t\t\t// a value outside ConnectionStatus's own type, and it disabled\n\t\t\t\t// checking on every other field at the same time.\n\t\t\t\t{\n\t\t\t\t\tid: res.connectionId,\n\t\t\t\t\tprovider: input.provider,\n\t\t\t\t\tconnected: false,\n\t\t\t\t\tdeclared: true,\n\t\t\t\t\trequired: false,\n\t\t\t\t\tendUserId: this.id,\n\t\t\t\t},\n\t\t\t\tres.authUrl,\n\t\t\t);\n\t\t},\n\n\t\t/** Theirs alone. The shared workspace and agent accounts are not here;\n\t\t *  `ws.connections.list()` is the view that shows those. */\n\t\tlist: async (): Promise<Connection[]> => {\n\t\t\t// WireConnection, not ConnectionStatus. The endpoint sends the wire\n\t\t\t// shape, and typing it as the SDK shape is what hid the whole bug:\n\t\t\t// `connected` is never sent, so every account here reported\n\t\t\t// `connected === undefined` while type-checking as a boolean.\n\t\t\tconst res = await this.#http.get<{ connections: WireConnection[] }>('/v1/connections', {\n\t\t\t\tendUserId: this.id,\n\t\t\t});\n\t\t\treturn (res.connections ?? [])\n\t\t\t\t.filter((c) => c.id)\n\t\t\t\t.map((c) => new Connection(this.#http, c.id, toConnectionStatus(c)));\n\t\t},\n\t};\n\n\t/**\n\t * Credentials that belong to THIS PERSON: their API key for a system you\n\t * integrate with, their token for a service only they have an account on.\n\t *\n\t * THIS WAS ABSENT UNTIL THERE WAS A WAY TO USE IT. A credential reaches a\n\t * turn only by being ATTACHED. A connection could be, by id; a secret could\n\t * not, because binding one took its VALUE, and you do not hold the value of a\n\t * secret the platform stored for you. So a per-person secret would have been\n\t * a surface that accepted writes, listed them back, and was read by nothing.\n\t * It was left out rather than shipped looking like a feature.\n\t *\n\t * `sessionBindings.secretIds` is what closed it, and attaching is still an\n\t * explicit line:\n\t *\n\t * ```ts\n\t * const ananya = ws.endUser(row.userId);\n\t * const key = await ananya.secrets.create({ name: 'ZENDESK_TOKEN', value: token });\n\t *\n\t * const conversation = await agent.start({ endUserId: ananya.id });\n\t * await conversation.attach(key);            // EXPLICIT. Nothing is implied.\n\t * ```\n\t *\n\t * TWO THINGS THE PLATFORM ENFORCES, neither of which you can turn off:\n\t * the agent must DECLARE that secret name at session scope, so attaching by\n\t * id is not a way around the allowlist; and a secret belonging to one end\n\t * user can only be attached to a conversation launched for that same person,\n\t * so one mistyped id cannot hand Ananya's key to somebody else's turn.\n\t */\n\treadonly secrets = {\n\t\t/** Store a credential for this person. The value is encrypted on arrival\n\t\t *  and never handed back, which is why attaching uses the id. */\n\t\tcreate: async (input: {\n\t\t\tname: string;\n\t\t\tvalue: string;\n\t\t\tdescription?: string;\n\t\t\tagentId?: string;\n\t\t}): Promise<Secret> => {\n\t\t\t// FIELDS PICKED, never the input object forwarded. Removing a field\n\t\t\t// from a type does not stop a JavaScript caller sending it, and\n\t\t\t// forwarding wholesale is how `endUserId` kept reaching the API after\n\t\t\t// it had supposedly been removed.\n\t\t\tconst res = await this.#http.post<{ secret?: SecretMeta } & SecretMeta>('/v1/secrets', {\n\t\t\t\tname: input.name,\n\t\t\t\tvalue: input.value,\n\t\t\t\tendUserId: this.id,\n\t\t\t\t...(input.description !== undefined && { description: input.description }),\n\t\t\t\t...(input.agentId !== undefined && { agentId: input.agentId }),\n\t\t\t});\n\t\t\tconst meta = res.secret ?? res;\n\t\t\treturn new Secret(this.#http, meta.id, meta);\n\t\t},\n\t\t/** This person's secrets, values excluded. The workspace's own are not in\n\t\t *  here: `ws.secrets.list()` answers that. */\n\t\tlist: async (): Promise<Secret[]> => {\n\t\t\tconst res = await this.#http.get<{ secrets: SecretMeta[] }>('/v1/secrets', {\n\t\t\t\tend_user_id: this.id,\n\t\t\t});\n\t\t\treturn (res.secrets ?? []).map((m) => new Secret(this.#http, m.id, m));\n\t\t},\n\t};\n\n\t/**\n\t * Everything this person has said, ACROSS EVERY AGENT, newest first.\n\t *\n\t * `agent.conversations({ endUser })` answers the narrower question, one agent\n\t * at a time. This is the one an application renders as \"your chats\", and it\n\t * is the only listing in this SDK with a real cursor: pass `before` from the\n\t * previous page to keep going, rather than being capped at 200.\n\t */\n\tasync conversations(options: { limit?: number; before?: string } = {}): Promise<Conversation[]> {\n\t\tconst res = await this.#http.get<{ conversations: AgentConversationData[] }>('/v1/conversations', {\n\t\t\tend_user_id: this.id,\n\t\t\t...(options.limit !== undefined && { limit: options.limit }),\n\t\t\t...(options.before && { before: options.before }),\n\t\t});\n\t\treturn (res.conversations ?? []).map((c) => new Conversation(this.#http, c.id, c));\n\t}\n\n\t/**\n\t * Cut this person off.\n\t *\n\t * Revokes every account they connected, so every conversation of theirs\n\t * stops acting as them from the next turn. What off-boarding calls, and the\n\t * reason it is one call rather than a loop the caller has to remember to\n\t * write.\n\t */\n\tasync revokeConnections(): Promise<void> {\n\t\tfor (const connection of await this.connections.list()) {\n\t\t\tawait connection.revoke();\n\t\t}\n\t}\n}\n"]}

package/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Every failure from this SDK is an AgentNavaError.
+ *
+ * One error type, not a hierarchy. A caller who wants to branch reads `code`,
+ * and a caller who wants to retry reads `retryable`; neither is helped by
+ * `instanceof NotFoundError`, and both are hurt by having to know which of nine
+ * classes a given call can throw.
+ */
+export declare class AgentNavaError extends Error {
+    /** Stable machine-readable reason, e.g. 'agent_not_found'.
+     *
+     *  BRANCH ON THIS, never on `message`. Messages are written for a person
+     *  reading a log and will be reworded; codes are part of the contract. */
+    readonly code: string;
+    /** The HTTP status. 404 covers both "no such thing" and "not yours", so a
+     *  caller probing ids cannot tell another customer's agent from one that
+     *  never existed. There is deliberately no 403. */
+    readonly status: number;
+    /** Whether trying the identical request again could succeed.
+     *
+     *  True for 5xx and 429 only. A 400 will fail the same way forever, and a
+     *  404 will not become found, so retrying either just turns one error into
+     *  several. This is the only thing worth automating on. */
+    readonly retryable: boolean;
+    /** Seconds to wait, on a 429 that said so. */
+    readonly retryAfter?: number;
+    /** The request id from the response, when there was one. Quote it to us and
+     *  we can find the exact request in our logs. */
+    readonly requestId?: string;
+    constructor(init: {
+        message: string;
+        code: string;
+        status: number;
+        retryAfter?: number;
+        requestId?: string;
+    });
+}
+/** A failure with no HTTP response behind it: DNS, a dropped socket, a timeout.
+ *
+ *  Reported as status 0 rather than invented as a 5xx, because a request that
+ *  never arrived is a different thing from one the server failed. It is
+ *  retryable for the same reason a 5xx is: nothing about the request was wrong. */
+export declare function networkError(message: string, cause?: unknown): AgentNavaError;

package/errors.js

@@ -0,0 +1,55 @@
+/**
+ * Every failure from this SDK is an AgentNavaError.
+ *
+ * One error type, not a hierarchy. A caller who wants to branch reads `code`,
+ * and a caller who wants to retry reads `retryable`; neither is helped by
+ * `instanceof NotFoundError`, and both are hurt by having to know which of nine
+ * classes a given call can throw.
+ */
+export class AgentNavaError extends Error {
+    /** Stable machine-readable reason, e.g. 'agent_not_found'.
+     *
+     *  BRANCH ON THIS, never on `message`. Messages are written for a person
+     *  reading a log and will be reworded; codes are part of the contract. */
+    code;
+    /** The HTTP status. 404 covers both "no such thing" and "not yours", so a
+     *  caller probing ids cannot tell another customer's agent from one that
+     *  never existed. There is deliberately no 403. */
+    status;
+    /** Whether trying the identical request again could succeed.
+     *
+     *  True for 5xx and 429 only. A 400 will fail the same way forever, and a
+     *  404 will not become found, so retrying either just turns one error into
+     *  several. This is the only thing worth automating on. */
+    retryable;
+    /** Seconds to wait, on a 429 that said so. */
+    retryAfter;
+    /** The request id from the response, when there was one. Quote it to us and
+     *  we can find the exact request in our logs. */
+    requestId;
+    constructor(init) {
+        super(init.message);
+        this.name = 'AgentNavaError';
+        this.code = init.code;
+        this.status = init.status;
+        this.retryable = init.status >= 500 || init.status === 429;
+        if (init.retryAfter !== undefined)
+            this.retryAfter = init.retryAfter;
+        if (init.requestId !== undefined)
+            this.requestId = init.requestId;
+    }
+}
+/** A failure with no HTTP response behind it: DNS, a dropped socket, a timeout.
+ *
+ *  Reported as status 0 rather than invented as a 5xx, because a request that
+ *  never arrived is a different thing from one the server failed. It is
+ *  retryable for the same reason a 5xx is: nothing about the request was wrong. */
+export function networkError(message, cause) {
+    const err = new AgentNavaError({ message, code: 'network_error', status: 0 });
+    // status 0 is not >= 500, so retryable has to be asserted here.
+    Object.defineProperty(err, 'retryable', { value: true, enumerable: true });
+    if (cause !== undefined)
+        Object.defineProperty(err, 'cause', { value: cause });
+    return err;
+}
+//# sourceMappingURL=errors.js.map

package/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACxC;;;8EAG0E;IACjE,IAAI,CAAS;IAEtB;;uDAEmD;IAC1C,MAAM,CAAS;IAExB;;;;+DAI2D;IAClD,SAAS,CAAU;IAE5B,8CAA8C;IACrC,UAAU,CAAU;IAE7B;qDACiD;IACxC,SAAS,CAAU;IAE5B,YAAY,IAMX;QACA,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;QAC3D,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACrE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACnE,CAAC;CACD;AAED;;;;mFAImF;AACnF,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,KAAe;IAC5D,MAAM,GAAG,GAAG,IAAI,cAAc,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9E,gEAAgE;IAChE,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3E,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/E,OAAO,GAAG,CAAC;AACZ,CAAC","sourcesContent":["/**\n * Every failure from this SDK is an AgentNavaError.\n *\n * One error type, not a hierarchy. A caller who wants to branch reads `code`,\n * and a caller who wants to retry reads `retryable`; neither is helped by\n * `instanceof NotFoundError`, and both are hurt by having to know which of nine\n * classes a given call can throw.\n */\nexport class AgentNavaError extends Error {\n\t/** Stable machine-readable reason, e.g. 'agent_not_found'.\n\t *\n\t *  BRANCH ON THIS, never on `message`. Messages are written for a person\n\t *  reading a log and will be reworded; codes are part of the contract. */\n\treadonly code: string;\n\n\t/** The HTTP status. 404 covers both \"no such thing\" and \"not yours\", so a\n\t *  caller probing ids cannot tell another customer's agent from one that\n\t *  never existed. There is deliberately no 403. */\n\treadonly status: number;\n\n\t/** Whether trying the identical request again could succeed.\n\t *\n\t *  True for 5xx and 429 only. A 400 will fail the same way forever, and a\n\t *  404 will not become found, so retrying either just turns one error into\n\t *  several. This is the only thing worth automating on. */\n\treadonly retryable: boolean;\n\n\t/** Seconds to wait, on a 429 that said so. */\n\treadonly retryAfter?: number;\n\n\t/** The request id from the response, when there was one. Quote it to us and\n\t *  we can find the exact request in our logs. */\n\treadonly requestId?: string;\n\n\tconstructor(init: {\n\t\tmessage: string;\n\t\tcode: string;\n\t\tstatus: number;\n\t\tretryAfter?: number;\n\t\trequestId?: string;\n\t}) {\n\t\tsuper(init.message);\n\t\tthis.name = 'AgentNavaError';\n\t\tthis.code = init.code;\n\t\tthis.status = init.status;\n\t\tthis.retryable = init.status >= 500 || init.status === 429;\n\t\tif (init.retryAfter !== undefined) this.retryAfter = init.retryAfter;\n\t\tif (init.requestId !== undefined) this.requestId = init.requestId;\n\t}\n}\n\n/** A failure with no HTTP response behind it: DNS, a dropped socket, a timeout.\n *\n *  Reported as status 0 rather than invented as a 5xx, because a request that\n *  never arrived is a different thing from one the server failed. It is\n *  retryable for the same reason a 5xx is: nothing about the request was wrong. */\nexport function networkError(message: string, cause?: unknown): AgentNavaError {\n\tconst err = new AgentNavaError({ message, code: 'network_error', status: 0 });\n\t// status 0 is not >= 500, so retryable has to be asserted here.\n\tObject.defineProperty(err, 'retryable', { value: true, enumerable: true });\n\tif (cause !== undefined) Object.defineProperty(err, 'cause', { value: cause });\n\treturn err;\n}\n"]}

package/http.d.ts

@@ -0,0 +1,32 @@
+export interface ClientOptions {
+    /** Defaults to `AGENTNAVA_API_KEY` from the environment. */
+    apiKey?: string;
+    /** Defaults to `https://api.agentnava.com`. */
+    baseURL?: string;
+    /** Per-request timeout in milliseconds. Default 60_000. */
+    timeout?: number;
+    /** Swap the fetch implementation, for tests or a proxy. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+    /** Sent as a JSON body. Mutually exclusive with `bytes`. */
+    body?: unknown;
+    /** Sent as the raw body, for file writes. Mutually exclusive with `body`. */
+    bytes?: ArrayBuffer | Uint8Array;
+    contentType?: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    signal?: AbortSignal;
+}
+export declare class Http {
+    #private;
+    constructor(options?: ClientOptions);
+    private url;
+    /** Make the request and hand back the raw Response, errors already thrown. */
+    send(path: string, options?: RequestOptions): Promise<Response>;
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    get<T>(path: string, query?: RequestOptions['query']): Promise<T>;
+    post<T>(path: string, body?: unknown, query?: RequestOptions['query']): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string, query?: RequestOptions['query']): Promise<T>;
+}