@soulcode/bexio-oauth 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soulcode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @soulcode/bexio-oauth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bexio OAuth token custody for Node apps. Connect Bexio accounts, store their tokens encrypted in Postgres, and get a valid access token anywhere, including background jobs, without two server instances ever refreshing the same token at once.
+
+It is **not** an auth framework: your app keeps its own login. For "Sign in with Bexio", let your auth framework run the login and hand the tokens over with `saveGrant()`.
+
+- Full guide: [docs/integration.md](https://github.com/SoulcodeAgency/bexio-oauth/blob/main/docs/integration.md)
+- Working examples (Better Auth, Supabase Auth): [examples/](https://github.com/SoulcodeAgency/bexio-oauth/tree/main/examples)
+
+## Install
+
+```bash
+npm install @soulcode/bexio-oauth pg
+npx @soulcode/bexio-oauth sql > migrations/0001_bexio_grants.sql   # then apply it
+npx @soulcode/bexio-oauth keygen                                    # encryption key
+```
+
+Requires Node ≥ 24 and PostgreSQL.
+
+## Quickstart
+
+```ts
+// lib/bexio.ts (server-only)
+import { Pool } from "pg";
+import { createBexioOAuth, postgresStore } from "@soulcode/bexio-oauth";
+
+export const bexio = createBexioOAuth({
+  clientId: process.env.BEXIO_CLIENT_ID!,
+  clientSecret: process.env.BEXIO_CLIENT_SECRET!,
+  redirectUri: process.env.BEXIO_REDIRECT_URI!, // e.g. https://app.example.com/api/bexio/callback
+  scopes: ["contact_show"],
+  keys: JSON.parse(process.env.BEXIO_TOKEN_KEYS!), // {"current":"k1","keys":{"k1":"<keygen>"}}
+  store: postgresStore(
+    new Pool({ connectionString: process.env.DATABASE_URL }),
+  ),
+});
+```
+
+```ts
+// GET /api/bexio/connect
+export const GET = async (req: Request) =>
+  bexio.start(req, {
+    ownerId: await currentWorkspaceId(req),
+    returnTo: "/settings",
+  });
+
+// GET /api/bexio/callback  (your redirectUri)
+export const GET = async (req: Request) =>
+  bexio.callback(req, { ownerId: await currentWorkspaceId(req) });
+```
+
+```ts
+// anywhere on the server, including cron jobs
+const { accessToken } = await bexio.getAccessToken({ ownerId: workspaceId });
+await fetch("https://api.bexio.com/2.0/contact", {
+  headers: {
+    Authorization: `Bearer ${accessToken}`,
+    Accept: "application/json",
+  },
+});
+```
+
+Also: `listGrants`, `disconnect`, `refreshIdle` (keep idle grants alive), `saveGrant` (tokens from your auth framework). Every error is a `BexioOAuthError` with a stable `code`.
+
+## License
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+process.exitCode = await run(process.argv.slice(2), (s) => process.stdout.write(s), (s) => process.stderr.write(s));
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,OAAO,CAAC,QAAQ,GAAG,MAAM,GAAG,CAC1B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EACrB,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAC9B,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAC/B,CAAC"}

package/dist/claims.d.ts

@@ -0,0 +1,31 @@
+/** Bexio's production OIDC issuer (Keycloak realm). */
+export declare const BEXIO_ISSUER = "https://auth.bexio.com/realms/bexio";
+/** Bexio's production API base URL. */
+export declare const BEXIO_API_BASE_URL = "https://api.bexio.com";
+/**
+ * Always requested. `company_profile` adds the company claims; `offline_access`
+ * issues a refresh token that keeps working without the user present.
+ */
+export declare const BASE_SCOPES: string[];
+export type ClaimBag = Record<string, unknown>;
+/** Who granted access, as read from Bexio's ID token, access token and userinfo. */
+export interface BexioIdentity {
+    /** OIDC `sub`. */
+    userId: string;
+    /** `company_id` (company_profile scope). */
+    companyId: string;
+    companyName: string | null;
+    /** `company_user_id` (access token): the user's id inside the company. */
+    companyUserId: number | null;
+    userName: string | null;
+    userEmail: string | null;
+}
+/**
+ * Maps a merged claim bag (ID token + access token + userinfo) to a
+ * `BexioIdentity`. Throws `invalid_callback` when `sub` or `company_id` is
+ * missing.
+ */
+export declare function mapClaims(claims: ClaimBag): BexioIdentity;
+/** The value a grant's ciphertext is bound to (see `TokenCipher`). */
+export declare function grantBinding(ownerId: string, companyId: string, userId: string): string;
+//# sourceMappingURL=claims.d.ts.map

package/dist/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,eAAO,MAAM,YAAY,wCAAwC,CAAC;AAClE,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAC1D;;;GAGG;AACH,eAAO,MAAM,WAAW,UAMvB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0EAA0E;IAC1E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAaD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,QAAQ,GAAG,aAAa,CAwBzD;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,CAER"}

package/dist/claims.js

@@ -0,0 +1,58 @@
+import { BexioOAuthError } from "./errors.js";
+/** Bexio's production OIDC issuer (Keycloak realm). */
+export const BEXIO_ISSUER = "https://auth.bexio.com/realms/bexio";
+/** Bexio's production API base URL. */
+export const BEXIO_API_BASE_URL = "https://api.bexio.com";
+/**
+ * Always requested. `company_profile` adds the company claims; `offline_access`
+ * issues a refresh token that keeps working without the user present.
+ */
+export const BASE_SCOPES = [
+    "openid",
+    "profile",
+    "email",
+    "company_profile",
+    "offline_access",
+];
+function text(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return null;
+}
+function integer(value) {
+    const parsed = typeof value === "string" ? Number.parseInt(value, 10) : value;
+    return typeof parsed === "number" && Number.isInteger(parsed) ? parsed : null;
+}
+/**
+ * Maps a merged claim bag (ID token + access token + userinfo) to a
+ * `BexioIdentity`. Throws `invalid_callback` when `sub` or `company_id` is
+ * missing.
+ */
+export function mapClaims(claims) {
+    const userId = text(claims.sub);
+    if (!userId)
+        throw new BexioOAuthError("invalid_callback", "missing sub claim");
+    const companyId = text(claims.company_id);
+    if (!companyId) {
+        throw new BexioOAuthError("invalid_callback", "missing company_id claim (is the company_profile scope requested?)");
+    }
+    const given = text(claims.given_name);
+    const family = text(claims.family_name);
+    return {
+        userId,
+        companyId,
+        companyName: text(claims.company_name),
+        companyUserId: integer(claims.company_user_id),
+        userName: given && family
+            ? `${given} ${family}`
+            : (text(claims.name) ?? given ?? family),
+        userEmail: text(claims.email),
+    };
+}
+/** The value a grant's ciphertext is bound to (see `TokenCipher`). */
+export function grantBinding(ownerId, companyId, userId) {
+    return `${ownerId}\u0000${companyId}\u0000${userId}`;
+}
+//# sourceMappingURL=claims.js.map

package/dist/claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,uDAAuD;AACvD,MAAM,CAAC,MAAM,YAAY,GAAG,qCAAqC,CAAC;AAClE,uCAAuC;AACvC,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAC1D;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,QAAQ;IACR,SAAS;IACT,OAAO;IACP,iBAAiB;IACjB,gBAAgB;CACjB,CAAC;AAiBF,SAAS,IAAI,CAAC,KAAc;IAC1B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAChE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,OAAO,CAAC,KAAc;IAC7B,MAAM,MAAM,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC9E,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAgB;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM;QACT,MAAM,IAAI,eAAe,CAAC,kBAAkB,EAAE,mBAAmB,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC1C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CACvB,kBAAkB,EAClB,oEAAoE,CACrE,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACxC,OAAO;QACL,MAAM;QACN,SAAS;QACT,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;QACtC,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC;QAC9C,QAAQ,EACN,KAAK,IAAI,MAAM;YACb,CAAC,CAAC,GAAG,KAAK,IAAI,MAAM,EAAE;YACtB,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,MAAM,CAAC;QAC5C,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;KAC9B,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,YAAY,CAC1B,OAAe,EACf,SAAiB,EACjB,MAAc;IAEd,OAAO,GAAG,OAAO,SAAS,SAAS,SAAS,MAAM,EAAE,CAAC;AACvD,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export declare function run(argv: string[], out: (s: string) => void, err: (s: string) => void): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAWA,wBAAsB,GAAG,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,EACxB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GACvB,OAAO,CAAC,MAAM,CAAC,CAgCjB"}

package/dist/cli.js

@@ -0,0 +1,44 @@
+import { generateKey } from "./crypto.js";
+import { migrations } from "./sql.js";
+const HELP = `Usage: bexio-oauth <command>
+
+Commands:
+  sql [--from <n>]   Print the schema SQL (all migrations, or from migration <n> on)
+  keygen             Print a new random 32-byte encryption key (base64url)
+  help               Show this help
+`;
+export async function run(argv, out, err) {
+    const [command, ...rest] = argv;
+    switch (command) {
+        case "sql": {
+            let from = 1;
+            if (rest[0] === "--from") {
+                from = Number.parseInt(rest[1] ?? "", 10);
+                if (!Number.isInteger(from) || from < 1) {
+                    err("--from needs a migration number, e.g. --from 2\n");
+                    return 1;
+                }
+            }
+            else if (rest.length > 0) {
+                err(HELP);
+                return 1;
+            }
+            const selected = (await migrations()).filter((m) => m.number >= from);
+            out(selected.map((m) => `-- ${m.name}\n${m.sql.trimEnd()}\n`).join("\n"));
+            return 0;
+        }
+        case "keygen":
+            out(`${generateKey()}\n`);
+            return 0;
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            out(HELP);
+            return 0;
+        default:
+            err(`Unknown command: ${command}\n\n${HELP}`);
+            return 1;
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,MAAM,IAAI,GAAG;;;;;;CAMZ,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,GAAG,CACvB,IAAc,EACd,GAAwB,EACxB,GAAwB;IAExB,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAChC,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,IAAI,IAAI,GAAG,CAAC,CAAC;YACb,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;gBACzB,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;gBAC1C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;oBACxC,GAAG,CAAC,kDAAkD,CAAC,CAAC;oBACxD,OAAO,CAAC,CAAC;gBACX,CAAC;YACH,CAAC;iBAAM,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,GAAG,CAAC,IAAI,CAAC,CAAC;gBACV,OAAO,CAAC,CAAC;YACX,CAAC;YACD,MAAM,QAAQ,GAAG,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;YACtE,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;YAC1E,OAAO,CAAC,CAAC;QACX,CAAC;QACD,KAAK,QAAQ;YACX,GAAG,CAAC,GAAG,WAAW,EAAE,IAAI,CAAC,CAAC;YAC1B,OAAO,CAAC,CAAC;QACX,KAAK,SAAS,CAAC;QACf,KAAK,MAAM,CAAC;QACZ,KAAK,QAAQ,CAAC;QACd,KAAK,IAAI;YACP,GAAG,CAAC,IAAI,CAAC,CAAC;YACV,OAAO,CAAC,CAAC;QACX;YACE,GAAG,CAAC,oBAAoB,OAAO,OAAO,IAAI,EAAE,CAAC,CAAC;YAC9C,OAAO,CAAC,CAAC;IACb,CAAC;AACH,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,140 @@
+import { type Keyring } from "./crypto.js";
+import { type Duration } from "./duration.js";
+import { type Role } from "./permissions.js";
+import type { GrantRecord, GrantStore } from "./store/types.js";
+export interface BexioOAuthConfig {
+    /** From your Bexio OAuth app. */
+    clientId: string;
+    clientSecret: string;
+    /** Must exactly match a redirect URI registered at Bexio. */
+    redirectUri: string;
+    /** Bexio API scopes your app needs; `BASE_SCOPES` are always added. */
+    scopes?: string[];
+    /** Encryption keyring (see `generateKey`). */
+    keys: Keyring;
+    store: GrantStore;
+    /** Defaults to Bexio's production issuer. Override only to point at a mock. */
+    issuer?: string;
+    /** Defaults to `https://api.bexio.com`. Override only to point at a mock. */
+    apiBaseUrl?: string;
+    /** How long one refresh may hold a grant's lock. Default `"30s"`. */
+    refreshLockTtl?: Duration;
+    /** Where `callback` redirects when the flow cookie is gone. Default `"/"`. */
+    defaultReturnTo?: string;
+    /** Custom `fetch` for every outgoing request (tests, proxies). */
+    fetch?: typeof fetch;
+    /** Clock override for tests. */
+    clock?: () => Date;
+}
+/** A grant as the app sees it: no token material. */
+export interface Grant {
+    id: string;
+    ownerId: string;
+    companyId: string;
+    companyName: string | null;
+    userId: string;
+    userName: string | null;
+    userEmail: string | null;
+    companyUserId: number | null;
+    role: Role;
+    status: GrantRecord["status"];
+    scope: string | null;
+    accessExpiresAt: Date | null;
+    lastRefreshedAt: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** Identifies one grant of an owner. */
+export interface GrantSelector {
+    ownerId: string;
+    companyId?: string;
+    grantId?: string;
+}
+export interface AccessToken {
+    accessToken: string;
+    expiresAt: Date | null;
+    grant: Grant;
+}
+/** Tokens obtained by your auth framework, for `saveGrant`. */
+export interface ExternalTokens {
+    accessToken: string;
+    refreshToken?: string | null;
+    idToken?: string | null;
+    /** Access-token expiry; defaults to the access token's `exp` claim. */
+    expiresAt?: Date | null;
+    scope?: string | null;
+}
+export interface RefreshIdleResult {
+    refreshed: number;
+    /** Idle grants another process was refreshing at the same time. */
+    skipped: number;
+    reauthRequired: number;
+    failed: number;
+}
+/**
+ * How the callback checks the owner. Either the `ownerId` your app derives
+ * from the signed-in session (must equal the one passed to `start`), or
+ * `authorizeOwner`, which receives the owner recorded at `start` and returns
+ * whether the signed-in user may connect Bexio for it. Use the latter when
+ * one callback URL serves many owners (e.g. workspaces).
+ */
+export type CallbackOptions = {
+    ownerId: string;
+} | {
+    authorizeOwner: (ownerId: string) => boolean | Promise<boolean>;
+};
+export interface CallbackResult {
+    grant: Grant;
+    returnTo: string;
+    /** Contains the `Set-Cookie` that deletes the flow cookie; copy it onto your response. */
+    headers: Headers;
+}
+export type BexioOAuth = ReturnType<typeof createBexioOAuth>;
+export declare function createBexioOAuth(config: BexioOAuthConfig): {
+    /**
+     * Starts the Connect flow: redirects to Bexio and sets the encrypted flow
+     * cookie. Derive `ownerId` from your authenticated session.
+     */
+    start(_request: Request, options: {
+        ownerId: string;
+        returnTo?: string;
+    }): Promise<Response>;
+    /**
+     * Handles the redirect back from Bexio and saves the grant. Throws a
+     * `BexioOAuthError` on failure; use `callback` for a ready-made redirect.
+     */
+    handleCallback(request: Request, options: CallbackOptions): Promise<CallbackResult>;
+    /**
+     * Handles the redirect back from Bexio, saves the grant, and redirects to
+     * `returnTo` (or `returnTo?bexio_error=<code>` on failure).
+     */
+    callback(request: Request, options: CallbackOptions): Promise<Response>;
+    /**
+     * Saves tokens obtained by your auth framework ("Sign in with Bexio").
+     * Verifies the tokens' signatures against Bexio's keys first.
+     */
+    saveGrant(input: {
+        ownerId: string;
+        tokens: ExternalTokens;
+    }): Promise<Grant>;
+    /**
+     * A valid access token for the owner's grant, refreshed when needed.
+     * Safe to call from background jobs and from many instances at once.
+     */
+    getAccessToken(selector: GrantSelector): Promise<AccessToken>;
+    /** The owner's grants, without token material. */
+    listGrants(query: {
+        ownerId: string;
+    }): Promise<Grant[]>;
+    /** Revokes the refresh token at Bexio (best effort) and deletes the grant. */
+    disconnect(selector: GrantSelector): Promise<void>;
+    /**
+     * Refreshes active grants not refreshed for `idleFor`, so Bexio doesn't end
+     * their offline sessions. Run it on a schedule.
+     */
+    refreshIdle(options: {
+        idleFor: Duration;
+        limit?: number;
+    }): Promise<RefreshIdleResult>;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAe,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhE,MAAM,WAAW,gBAAgB;IAC/B,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,8CAA8C;IAC9C,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,UAAU,CAAC;IAClB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC1B,8EAA8E;IAC9E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,qDAAqD;AACrD,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,IAAI,CAAC;IACtB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uEAAuE;IACvE,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACnB;IAAE,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,OAAO,EAAE,OAAO,CAAC;CAClB;AAqHD,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE7D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB;IAuQrD;;;OAGG;oBAES,OAAO,WACR;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAC9C,OAAO,CAAC,QAAQ,CAAC;IAmCpB;;;OAGG;4BAEQ,OAAO,WACP,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC;IAyG1B;;;OAGG;sBAEQ,OAAO,WACP,eAAe,GACvB,OAAO,CAAC,QAAQ,CAAC;IAqBpB;;;OAGG;qBACoB;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,cAAc,CAAC;KACxB,GAAG,OAAO,CAAC,KAAK,CAAC;IA4FlB;;;OAGG;6BAC4B,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC;IAkDnE,kDAAkD;sBAC1B;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAM9D,8EAA8E;yBACnD,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBxD;;;OAGG;yBACwB;QACzB,OAAO,EAAE,QAAQ,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,iBAAiB,CAAC;EA2DjC"}