@cerebro-labs/agentnava-sdk 0.26.0 → 0.46.1

package/account.js

@@ -0,0 +1,219 @@
+// An account: one saved sign-in to one app.
+import { AgentNavaError } from "./errors.js";
+/**
+ * One saved sign-in to one app, that you hold and act on.
+ *
+ * AN ACCOUNT IS NOT A CONNECTION, and the two words used to be one, which is
+ * how an agent came to own a Gmail login that nothing else could see. An
+ * ACCOUNT is a sign-in: Gmail, signed in as support@example.com. A CONNECTION is
+ * an entry in an agent's setup that names one: "this agent uses Gmail, through
+ * that account". Many agents can name one account, and reconnecting it once
+ * fixes all of them.
+ *
+ * ```ts
+ * const { account, url } = await ws.accounts.connect({ app: App.GMAIL, nickname: 'Support inbox' });
+ * showToUser(url);                        // they sign in on Google's own page
+ * await account.waitUntilConnected();
+ * await agent.connections.add(Connection.creatorAccount(App.GMAIL, account));
+ * ```
+ *
+ * Nobody handles a token, you included: the person signs in on the app's own
+ * page, and this object says who they signed in as, never how.
+ *
+ * ONE KIND OF OBJECT FOR BOTH OWNERS. The agent creator's account and one of
+ * your end users' are the same class, reached by the same routes: every method
+ * here works on any account in the workspace, and `data.owner` says whose it
+ * is. So `ws.account(id).waitUntilConnected()` is how you wait for an end user
+ * to finish signing in, too.
+ *
+ * A CLASS, like `Database` and `Secret`: you hold it and act on it, rather than
+ * threading an id through calls. Holding one makes no request. `ws.account(id)`
+ * is free and the first call on it is the first round trip.
+ */
+export class Account {
+    id;
+    #http;
+    snapshot;
+    constructor(http, id, snapshot) {
+        this.#http = http;
+        this.id = id;
+        if (snapshot)
+            this.snapshot = snapshot;
+    }
+    get base() {
+        return `/v1/accounts/${encodeURIComponent(this.id)}`;
+    }
+    /** The app's catalog id: `'gmail'`, `'hubspot'`. Named for what the person
+     *  signing in recognises, never for whoever we buy the sign-in from. */
+    get app() {
+        return this.snapshot?.app;
+    }
+    /** Who it is signed in as: the email or username the app reports. Null until
+     *  somebody has finished signing in. */
+    get label() {
+        return this.snapshot?.label;
+    }
+    /** Your own name for it, such as `'Support inbox'`. */
+    get nickname() {
+        return this.snapshot?.nickname;
+    }
+    /** Where the sign-in stands, from the last read: `'pending'`, `'connected'`,
+     *  `'needs_sign_in'` or `'error'`.
+     *
+     *  Reads the snapshot rather than the network. Undefined means this handle
+     *  has not read yet, NOT that the account is disconnected: call `get()`. */
+    get status() {
+        return this.snapshot?.status;
+    }
+    /** The agents whose setup names this account, from the last read. The
+     *  question to ask before disconnecting it: who loses it? */
+    get usedBy() {
+        return this.snapshot?.usedBy;
+    }
+    /** The last-known record, from whatever call produced this object. */
+    get data() {
+        return this.snapshot;
+    }
+    /**
+     * An account goes over the wire as its id, the way a `Date` goes as its ISO
+     * string: `JSON.stringify({ account })` sends `"acc_..."`.
+     *
+     * That is what lets a connection written as a plain object,
+     * `{ app, account }`, take the Account you are holding in
+     * `ws.agents.create()` and `agent.update()`. It also matches the rule for
+     * every handle in this SDK: store the id, not the object.
+     */
+    toJSON() {
+        return this.id;
+    }
+    /**
+     * Read it back.
+     *
+     * A MISSING ACCOUNT THROWS (`account_not_found`, 404), and never comes back
+     * as an empty record. An account that does not exist and one that is not
+     * signed in yet are different answers. The connection this replaced once
+     * answered a miss with a made-up blank, so storing an id and reading it back
+     * gave you something that did not know what it was.
+     */
+    async get() {
+        const res = await this.#http.get(this.base);
+        this.snapshot = accountIn(res, this.base);
+        return this.snapshot;
+    }
+    /**
+     * Wait until the person has finished signing in.
+     *
+     * The companion to `ws.accounts.connect()`, `ws.endUser(id).accounts
+     * .connect()` and `reconnect()`. Those hand you a url; this tells you when
+     * the person is done, so you do not write a polling loop or guess which
+     * field to believe.
+     *
+     * DONE MEANS CONNECTED AND NOT RECONNECTING. During a reconnect the account
+     * keeps working (`status` stays `'connected'`) while `reconnecting` is true,
+     * so a check on `status` alone would return before the person had signed in
+     * again. This waits for both.
+     *
+     * THROWS on the deadline (`account_not_connected`), naming the account and
+     * where it stands, rather than returning an account that is still pending.
+     * Safe to call again: somebody who has not finished may just need longer.
+     *
+     * Polls rather than subscribing: there is a person in the middle, so a few
+     * seconds costs nothing, and it works from any runtime without a socket.
+     */
+    async waitUntilConnected(options = {}) {
+        const timeoutMs = options.timeoutMs ?? 120_000;
+        const intervalMs = options.intervalMs ?? 2_000;
+        const deadline = Date.now() + timeoutMs;
+        // Checked before the first sleep: an account that is already connected
+        // should cost one request, not one request plus an interval.
+        let state = await this.get();
+        while (state.status !== 'connected' || state.reconnecting) {
+            if (Date.now() >= deadline) {
+                throw new AgentNavaError({
+                    message: `Account ${this.id} (${state.app}) was not connected within ${timeoutMs}ms; it is still ${state.status}${state.reconnecting ? ', with a reconnect waiting for the person' : ''}`,
+                    code: 'account_not_connected',
+                    status: 0,
+                });
+            }
+            await new Promise((r) => setTimeout(r, Math.min(intervalMs, Math.max(0, deadline - Date.now()))));
+            state = await this.get();
+        }
+        return this;
+    }
+    /**
+     * Send the person to sign in again, and get the link.
+     *
+     * What to call when an account `needs_sign_in`. Every agent that names it
+     * follows, so reconnecting once fixes all of them. The sign-in that worked is
+     * kept until the new one succeeds, so an abandoned link breaks nothing:
+     * meanwhile `data.reconnecting` is true, and `waitUntilConnected()` waits
+     * for it to clear.
+     *
+     * If the person signs in as SOMEBODY ELSE, that becomes a NEW account and
+     * this one is left as it was, so no agent switches mailbox without anyone
+     * deciding it should. List accounts to find the new one, then change the
+     * connections that should use it.
+     */
+    async reconnect() {
+        const res = await this.#http.post(`${this.base}/reconnect`);
+        return { url: res.url };
+    }
+    /** Give it your own name, such as `'Support inbox'`, shown beside who it is
+     *  signed in as. The app and the sign-in do not change. */
+    async rename(nickname) {
+        const res = await this.#http.patch(this.base, { nickname });
+        this.snapshot = accountIn(res, this.base);
+        return this;
+    }
+    /** Ask the app whether the sign-in still works, and read the answer. A
+     *  revoked sign-in comes back as `needs_sign_in`, not as an exception: it is
+     *  the answer this call exists to get. */
+    async check() {
+        const res = await this.#http.post(`${this.base}/check`);
+        this.snapshot = accountIn(res, `${this.base}/check`);
+        return this.snapshot;
+    }
+    /**
+     * Sign it out at the app and remove it here.
+     *
+     * ALWAYS ALLOWED, unlike deleting a database that an agent still names. It
+     * returns the agents whose setup names the account, so you can tell whoever
+     * owns them: from their next turn those connections report that the account
+     * was disconnected. Nothing switches to another account in its place.
+     *
+     * Removing a connection from an agent is the other thing, and it never
+     * touches the account: `agent.connections.remove(name)`.
+     */
+    async disconnect() {
+        // The same route for either owner. An end user's account is never named
+        // by an agent's setup (that says `endUser: true`), so for one of those
+        // the list of agents is empty, which is the true answer.
+        const res = await this.#http.delete(this.base);
+        return { agents: res?.agents ?? [] };
+    }
+}
+/**
+ * The account a response carries, or a thrown error. Never a blank.
+ *
+ * A 404 already throws in the transport, with the API's `account_not_found`.
+ * This covers the other way to end up with nothing: a 200 whose body has no
+ * account in it, which would otherwise become a snapshot of `undefined` that
+ * reads, at every call site, exactly like an account nobody has read yet.
+ */
+export function accountIn(res, path) {
+    const account = res?.account;
+    if (!account || typeof account.id !== 'string') {
+        throw new AgentNavaError({
+            message: `Expected an account from ${path}, got: ${JSON.stringify(res ?? null).slice(0, 200)}`,
+            code: 'bad_response',
+            status: 200,
+        });
+    }
+    return account;
+}
+/** The id a connection sends for its account: an `Account` by its id, an id
+ *  as it is. */
+export function accountIdOf(account) {
+    return typeof account === 'string' ? account : account?.id;
+}
+//# sourceMappingURL=account.js.map

package/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"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","sourcesContent":["// An account: one saved sign-in to one app.\n\nimport { AgentNavaError } from './errors.ts';\nimport type { Http } from './http.ts';\nimport type { AccountData, AccountStatus, UsedBy } from './types.ts';\n\n/**\n * One saved sign-in to one app, that you hold and act on.\n *\n * AN ACCOUNT IS NOT A CONNECTION, and the two words used to be one, which is\n * how an agent came to own a Gmail login that nothing else could see. An\n * ACCOUNT is a sign-in: Gmail, signed in as support@example.com. A CONNECTION is\n * an entry in an agent's setup that names one: \"this agent uses Gmail, through\n * that account\". Many agents can name one account, and reconnecting it once\n * fixes all of them.\n *\n * ```ts\n * const { account, url } = await ws.accounts.connect({ app: App.GMAIL, nickname: 'Support inbox' });\n * showToUser(url);                        // they sign in on Google's own page\n * await account.waitUntilConnected();\n * await agent.connections.add(Connection.creatorAccount(App.GMAIL, account));\n * ```\n *\n * Nobody handles a token, you included: the person signs in on the app's own\n * page, and this object says who they signed in as, never how.\n *\n * ONE KIND OF OBJECT FOR BOTH OWNERS. The agent creator's account and one of\n * your end users' are the same class, reached by the same routes: every method\n * here works on any account in the workspace, and `data.owner` says whose it\n * is. So `ws.account(id).waitUntilConnected()` is how you wait for an end user\n * to finish signing in, too.\n *\n * A CLASS, like `Database` and `Secret`: you hold it and act on it, rather than\n * threading an id through calls. Holding one makes no request. `ws.account(id)`\n * is free and the first call on it is the first round trip.\n */\nexport class Account {\n\treadonly id: string;\n\treadonly #http: Http;\n\tprivate snapshot?: AccountData;\n\n\tconstructor(http: Http, id: string, snapshot?: AccountData) {\n\t\tthis.#http = http;\n\t\tthis.id = id;\n\t\tif (snapshot) this.snapshot = snapshot;\n\t}\n\n\tprivate get base(): string {\n\t\treturn `/v1/accounts/${encodeURIComponent(this.id)}`;\n\t}\n\n\t/** The app's catalog id: `'gmail'`, `'hubspot'`. Named for what the person\n\t *  signing in recognises, never for whoever we buy the sign-in from. */\n\tget app(): string | undefined {\n\t\treturn this.snapshot?.app;\n\t}\n\n\t/** Who it is signed in as: the email or username the app reports. Null until\n\t *  somebody has finished signing in. */\n\tget label(): string | null | undefined {\n\t\treturn this.snapshot?.label;\n\t}\n\n\t/** Your own name for it, such as `'Support inbox'`. */\n\tget nickname(): string | null | undefined {\n\t\treturn this.snapshot?.nickname;\n\t}\n\n\t/** Where the sign-in stands, from the last read: `'pending'`, `'connected'`,\n\t *  `'needs_sign_in'` or `'error'`.\n\t *\n\t *  Reads the snapshot rather than the network. Undefined means this handle\n\t *  has not read yet, NOT that the account is disconnected: call `get()`. */\n\tget status(): AccountStatus | undefined {\n\t\treturn this.snapshot?.status;\n\t}\n\n\t/** The agents whose setup names this account, from the last read. The\n\t *  question to ask before disconnecting it: who loses it? */\n\tget usedBy(): UsedBy[] | undefined {\n\t\treturn this.snapshot?.usedBy;\n\t}\n\n\t/** The last-known record, from whatever call produced this object. */\n\tget data(): AccountData | undefined {\n\t\treturn this.snapshot;\n\t}\n\n\t/**\n\t * An account goes over the wire as its id, the way a `Date` goes as its ISO\n\t * string: `JSON.stringify({ account })` sends `\"acc_...\"`.\n\t *\n\t * That is what lets a connection written as a plain object,\n\t * `{ app, account }`, take the Account you are holding in\n\t * `ws.agents.create()` and `agent.update()`. It also matches the rule for\n\t * every handle in this SDK: store the id, not the object.\n\t */\n\ttoJSON(): string {\n\t\treturn this.id;\n\t}\n\n\t/**\n\t * Read it back.\n\t *\n\t * A MISSING ACCOUNT THROWS (`account_not_found`, 404), and never comes back\n\t * as an empty record. An account that does not exist and one that is not\n\t * signed in yet are different answers. The connection this replaced once\n\t * answered a miss with a made-up blank, so storing an id and reading it back\n\t * gave you something that did not know what it was.\n\t */\n\tasync get(): Promise<AccountData> {\n\t\tconst res = await this.#http.get<{ account?: AccountData }>(this.base);\n\t\tthis.snapshot = accountIn(res, this.base);\n\t\treturn this.snapshot;\n\t}\n\n\t/**\n\t * Wait until the person has finished signing in.\n\t *\n\t * The companion to `ws.accounts.connect()`, `ws.endUser(id).accounts\n\t * .connect()` and `reconnect()`. Those hand you a url; this tells you when\n\t * the person is done, so you do not write a polling loop or guess which\n\t * field to believe.\n\t *\n\t * DONE MEANS CONNECTED AND NOT RECONNECTING. During a reconnect the account\n\t * keeps working (`status` stays `'connected'`) while `reconnecting` is true,\n\t * so a check on `status` alone would return before the person had signed in\n\t * again. This waits for both.\n\t *\n\t * THROWS on the deadline (`account_not_connected`), naming the account and\n\t * where it stands, rather than returning an account that is still pending.\n\t * Safe to call again: somebody who has not finished may just need longer.\n\t *\n\t * Polls rather than subscribing: there is a person in the middle, so a few\n\t * seconds costs nothing, and it works from any runtime without a socket.\n\t */\n\tasync waitUntilConnected(options: { timeoutMs?: number; intervalMs?: number } = {}): Promise<Account> {\n\t\tconst timeoutMs = options.timeoutMs ?? 120_000;\n\t\tconst intervalMs = options.intervalMs ?? 2_000;\n\t\tconst deadline = Date.now() + timeoutMs;\n\t\t// Checked before the first sleep: an account that is already connected\n\t\t// should cost one request, not one request plus an interval.\n\t\tlet state = await this.get();\n\t\twhile (state.status !== 'connected' || state.reconnecting) {\n\t\t\tif (Date.now() >= deadline) {\n\t\t\t\tthrow new AgentNavaError({\n\t\t\t\t\tmessage: `Account ${this.id} (${state.app}) was not connected within ${timeoutMs}ms; it is still ${state.status}${\n\t\t\t\t\t\tstate.reconnecting ? ', with a reconnect waiting for the person' : ''\n\t\t\t\t\t}`,\n\t\t\t\t\tcode: 'account_not_connected',\n\t\t\t\t\tstatus: 0,\n\t\t\t\t});\n\t\t\t}\n\t\t\tawait new Promise((r) => setTimeout(r, Math.min(intervalMs, Math.max(0, deadline - Date.now()))));\n\t\t\tstate = await this.get();\n\t\t}\n\t\treturn this;\n\t}\n\n\t/**\n\t * Send the person to sign in again, and get the link.\n\t *\n\t * What to call when an account `needs_sign_in`. Every agent that names it\n\t * follows, so reconnecting once fixes all of them. The sign-in that worked is\n\t * kept until the new one succeeds, so an abandoned link breaks nothing:\n\t * meanwhile `data.reconnecting` is true, and `waitUntilConnected()` waits\n\t * for it to clear.\n\t *\n\t * If the person signs in as SOMEBODY ELSE, that becomes a NEW account and\n\t * this one is left as it was, so no agent switches mailbox without anyone\n\t * deciding it should. List accounts to find the new one, then change the\n\t * connections that should use it.\n\t */\n\tasync reconnect(): Promise<{ url: string }> {\n\t\tconst res = await this.#http.post<{ url: string }>(`${this.base}/reconnect`);\n\t\treturn { url: res.url };\n\t}\n\n\t/** Give it your own name, such as `'Support inbox'`, shown beside who it is\n\t *  signed in as. The app and the sign-in do not change. */\n\tasync rename(nickname: string): Promise<Account> {\n\t\tconst res = await this.#http.patch<{ account?: AccountData }>(this.base, { nickname });\n\t\tthis.snapshot = accountIn(res, this.base);\n\t\treturn this;\n\t}\n\n\t/** Ask the app whether the sign-in still works, and read the answer. A\n\t *  revoked sign-in comes back as `needs_sign_in`, not as an exception: it is\n\t *  the answer this call exists to get. */\n\tasync check(): Promise<AccountData> {\n\t\tconst res = await this.#http.post<{ account?: AccountData }>(`${this.base}/check`);\n\t\tthis.snapshot = accountIn(res, `${this.base}/check`);\n\t\treturn this.snapshot;\n\t}\n\n\t/**\n\t * Sign it out at the app and remove it here.\n\t *\n\t * ALWAYS ALLOWED, unlike deleting a database that an agent still names. It\n\t * returns the agents whose setup names the account, so you can tell whoever\n\t * owns them: from their next turn those connections report that the account\n\t * was disconnected. Nothing switches to another account in its place.\n\t *\n\t * Removing a connection from an agent is the other thing, and it never\n\t * touches the account: `agent.connections.remove(name)`.\n\t */\n\tasync disconnect(): Promise<{ agents: UsedBy[] }> {\n\t\t// The same route for either owner. An end user's account is never named\n\t\t// by an agent's setup (that says `endUser: true`), so for one of those\n\t\t// the list of agents is empty, which is the true answer.\n\t\tconst res = await this.#http.delete<{ disconnected?: boolean; agents?: UsedBy[] }>(this.base);\n\t\treturn { agents: res?.agents ?? [] };\n\t}\n}\n\n/**\n * The account a response carries, or a thrown error. Never a blank.\n *\n * A 404 already throws in the transport, with the API's `account_not_found`.\n * This covers the other way to end up with nothing: a 200 whose body has no\n * account in it, which would otherwise become a snapshot of `undefined` that\n * reads, at every call site, exactly like an account nobody has read yet.\n */\nexport function accountIn(res: { account?: AccountData } | undefined, path: string): AccountData {\n\tconst account = res?.account;\n\tif (!account || typeof account.id !== 'string') {\n\t\tthrow new AgentNavaError({\n\t\t\tmessage: `Expected an account from ${path}, got: ${JSON.stringify(res ?? null).slice(0, 200)}`,\n\t\t\tcode: 'bad_response',\n\t\t\tstatus: 200,\n\t\t});\n\t}\n\treturn account;\n}\n\n/** The id a connection sends for its account: an `Account` by its id, an id\n *  as it is. */\nexport function accountIdOf(account: Account | string): string {\n\treturn typeof account === 'string' ? account : account?.id;\n}\n"]}