@cboxdk/id-js 0.18.0 → 0.20.0

package/dist/{client-BxUHm5hX.d.cts → client-BT-jOm0p.d.cts}

@@ -1,4 +1,5 @@
-import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-BYZldock.cjs';
+import { C as CboxIdError } from './errors-D61xljZE.cjs';
+import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-CC1bz68x.cjs';
 
 /** A stored vault secret's metadata (never its plaintext). */
 interface VaultSecretRef {
@@ -17,6 +18,98 @@ interface VaultLease {
     secret: string;
     expiresAt: string;
 }
+/** A provider a pipe can connect to. */
+type PipeProvider = 'github' | 'google' | 'microsoft' | 'slack' | 'salesforce' | 'hubspot' | 'linear' | 'notion';
+/**
+ * A fresh access token for one person's connected account at a provider — what
+ * {@link VaultClient.leasePipeToken} returns. Use it, drop it, lease again next time.
+ */
+interface PipeToken {
+    /** The provider's access token. Send it as a bearer token to the provider's API. */
+    accessToken: string;
+    tokenType: 'Bearer';
+    provider: string;
+    userId: string;
+    connectionId: string;
+    /** What the person consented to. */
+    scopes: string[];
+    /** When the PROVIDER stops accepting it; null for tokens that do not expire. */
+    expiresAt: string | null;
+    /** When to drop it and lease again. */
+    leaseExpiresAt: string;
+    /** What some providers need to be called at all — Salesforce's `instance_url`, Slack's `team.id`. */
+    metadata: Record<string, string>;
+}
+/** Where a person connects a provider, and where they come back to afterwards. */
+interface PipeConnectOptions {
+    /** Your app's client id — the connect page shows its name and allows its origins. */
+    clientId?: string;
+    /**
+     * Where to land afterwards, with `?provider=…&status=connected|cancelled|failed`. Must be
+     * on one of the app's registered redirect origins, or it is ignored.
+     */
+    returnTo?: string;
+}
+/**
+ * Add `client_id` and `return_to` to a connect URL — the one a lease error carries, or
+ * one built with {@link pipeConnectUrl}.
+ */
+declare function withConnectReturn(connectUrl: string, options?: PipeConnectOptions): string;
+/**
+ * The hosted page where the signed-in person connects their account at `provider`:
+ * `{issuer}/account/connected-services/{provider}/connect?client_id=…&return_to=…`.
+ */
+declare function pipeConnectUrl(issuer: string, provider: PipeProvider | string, options?: PipeConnectOptions): string;
+/**
+ * A pipe token lease was refused. Catch the subclasses for the cases you can act on:
+ *
+ *  - {@link PipeNotConnectedError} (404) and {@link PipeReauthorizationRequiredError}
+ *    (409) — send the person to `connectUrl`.
+ *  - {@link PipeTemporarilyUnavailableError} (503) — retry after `retryAfter` seconds.
+ *  - {@link PipeLeaseDeniedError} (403) — a configuration problem: the app is not granted
+ *    the pipe, it is disabled, or the person is outside the app's organization.
+ *
+ * Anything else (401, 422, 429) arrives as this base class with `status` and `error`.
+ */
+declare class PipeLeaseError extends CboxIdError {
+    /** The server's error code, e.g. `not_connected`. */
+    readonly error: string | null;
+    readonly status: number;
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    readonly connectUrl: string | null;
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    readonly retryAfter: number | null;
+    constructor(message: string, 
+    /** The server's error code, e.g. `not_connected`. */
+    error: string | null, status: number, 
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    connectUrl?: string | null, 
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    retryAfter?: number | null);
+    /** `connectUrl` with your `client_id` and `return_to` on it, or null when there is none. */
+    connectUrlWith(options: PipeConnectOptions): string | null;
+}
+/** The person has not connected this provider (404 `not_connected`). Send them to `connectUrl`. */
+declare class PipeNotConnectedError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/**
+ * The provider stopped accepting the connection — revoked, or the refresh token expired
+ * (409 `reauthorization_required`). Send the person to `connectUrl` to connect again.
+ */
+declare class PipeReauthorizationRequiredError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/** The provider could not refresh the token just now (503). Retry after `retryAfter`. */
+declare class PipeTemporarilyUnavailableError extends PipeLeaseError {
+}
+/**
+ * The lease was denied (403 `lease_denied`): the app is not granted the pipe, the pipe is
+ * disabled or missing, the person is not in the app's organization, or `userId` names
+ * someone other than the token's person. One answer for every reason, by design.
+ */
+declare class PipeLeaseDeniedError extends PipeLeaseError {
+}
 interface StoreSecretInput {
     name: string;
     provider: string;
@@ -54,8 +147,32 @@ declare class VaultClient {
      * is identified by the token's client; a lease with no live grant is refused.
      */
     lease(secretId: string, purpose: string): Promise<VaultLease>;
+    /**
+     * Lease a fresh access token for a person's connected account at `provider` (Pipes,
+     * scope `vault.lease`). The token is refreshed first when it is about to expire, so
+     * you never handle a refresh token.
+     *
+     * With a client-credentials token, name the person in `userId`. With a token issued to
+     * your app FOR a person, leave it out — the lease is theirs.
+     *
+     * ```ts
+     * try {
+     *   const { accessToken } = await vault.leasePipeToken('github', { userId, purpose: 'list-repos' })
+     * } catch (e) {
+     *   if (e instanceof PipeNotConnectedError || e instanceof PipeReauthorizationRequiredError) {
+     *     return redirect(e.connectUrlWith({ clientId, returnTo }))
+     *   }
+     *   throw e
+     * }
+     * ```
+     */
+    leasePipeToken(provider: PipeProvider | string, options: {
+        purpose: string;
+        userId?: string;
+    }): Promise<PipeToken>;
     private json;
     private request;
+    private send;
 }
 
 /**
@@ -259,6 +376,13 @@ declare class CboxIdClient {
      * registered. `organization` picks which of the person's organizations the keys act in;
      * omitted, the page uses the one they are in.
      */
+    /**
+     * The hosted page where the signed-in person connects their account at `provider`
+     * (Pipes) — `/account/connected-services/{provider}/connect`, preselected to this app.
+     * They come back to `returnTo` with `?provider=…&status=connected|cancelled|failed`,
+     * honoured only on an origin the app registered.
+     */
+    pipeConnectUrl(provider: PipeProvider | string, returnTo?: string): string;
     apiKeysUrl(options?: {
         clientId?: string;
         returnTo?: string;
@@ -338,4 +462,4 @@ declare class CboxIdClient {
     private fetchWithTimeout;
 }
 
-export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyStandardWebhookOptions as e, type VerifyWebhookOptions as f, verifyWebhook as g, verifyStandardWebhook as v };
+export { CboxIdClient as C, type PipeConnectOptions as P, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, PipeLeaseDeniedError as b, PipeLeaseError as c, PipeNotConnectedError as d, type PipeProvider as e, PipeReauthorizationRequiredError as f, PipeTemporarilyUnavailableError as g, type PipeToken as h, type StoredAuthState as i, type VaultLease as j, type VaultSecretRef as k, type VerifyStandardWebhookOptions as l, type VerifyWebhookOptions as m, verifyWebhook as n, pipeConnectUrl as p, verifyStandardWebhook as v, withConnectReturn as w };

package/dist/{client-BSZASrMo.d.ts → client-xlEJalu8.d.ts}

@@ -1,4 +1,5 @@
-import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-BYZldock.js';
+import { C as CboxIdError } from './errors-D61xljZE.js';
+import { a as CboxIdConfig, A as AuthorizationRequestOptions, b as AuthorizationRequest, C as CboxUser, D as DeviceAuthorization, R as RefreshedTokens, T as TokenTypeHint } from './types-CC1bz68x.js';
 
 /** A stored vault secret's metadata (never its plaintext). */
 interface VaultSecretRef {
@@ -17,6 +18,98 @@ interface VaultLease {
     secret: string;
     expiresAt: string;
 }
+/** A provider a pipe can connect to. */
+type PipeProvider = 'github' | 'google' | 'microsoft' | 'slack' | 'salesforce' | 'hubspot' | 'linear' | 'notion';
+/**
+ * A fresh access token for one person's connected account at a provider — what
+ * {@link VaultClient.leasePipeToken} returns. Use it, drop it, lease again next time.
+ */
+interface PipeToken {
+    /** The provider's access token. Send it as a bearer token to the provider's API. */
+    accessToken: string;
+    tokenType: 'Bearer';
+    provider: string;
+    userId: string;
+    connectionId: string;
+    /** What the person consented to. */
+    scopes: string[];
+    /** When the PROVIDER stops accepting it; null for tokens that do not expire. */
+    expiresAt: string | null;
+    /** When to drop it and lease again. */
+    leaseExpiresAt: string;
+    /** What some providers need to be called at all — Salesforce's `instance_url`, Slack's `team.id`. */
+    metadata: Record<string, string>;
+}
+/** Where a person connects a provider, and where they come back to afterwards. */
+interface PipeConnectOptions {
+    /** Your app's client id — the connect page shows its name and allows its origins. */
+    clientId?: string;
+    /**
+     * Where to land afterwards, with `?provider=…&status=connected|cancelled|failed`. Must be
+     * on one of the app's registered redirect origins, or it is ignored.
+     */
+    returnTo?: string;
+}
+/**
+ * Add `client_id` and `return_to` to a connect URL — the one a lease error carries, or
+ * one built with {@link pipeConnectUrl}.
+ */
+declare function withConnectReturn(connectUrl: string, options?: PipeConnectOptions): string;
+/**
+ * The hosted page where the signed-in person connects their account at `provider`:
+ * `{issuer}/account/connected-services/{provider}/connect?client_id=…&return_to=…`.
+ */
+declare function pipeConnectUrl(issuer: string, provider: PipeProvider | string, options?: PipeConnectOptions): string;
+/**
+ * A pipe token lease was refused. Catch the subclasses for the cases you can act on:
+ *
+ *  - {@link PipeNotConnectedError} (404) and {@link PipeReauthorizationRequiredError}
+ *    (409) — send the person to `connectUrl`.
+ *  - {@link PipeTemporarilyUnavailableError} (503) — retry after `retryAfter` seconds.
+ *  - {@link PipeLeaseDeniedError} (403) — a configuration problem: the app is not granted
+ *    the pipe, it is disabled, or the person is outside the app's organization.
+ *
+ * Anything else (401, 422, 429) arrives as this base class with `status` and `error`.
+ */
+declare class PipeLeaseError extends CboxIdError {
+    /** The server's error code, e.g. `not_connected`. */
+    readonly error: string | null;
+    readonly status: number;
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    readonly connectUrl: string | null;
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    readonly retryAfter: number | null;
+    constructor(message: string, 
+    /** The server's error code, e.g. `not_connected`. */
+    error: string | null, status: number, 
+    /** Where to send the person to (re)connect — set on 404 and 409. */
+    connectUrl?: string | null, 
+    /** Seconds to wait off `Retry-After`, when the server sent one. */
+    retryAfter?: number | null);
+    /** `connectUrl` with your `client_id` and `return_to` on it, or null when there is none. */
+    connectUrlWith(options: PipeConnectOptions): string | null;
+}
+/** The person has not connected this provider (404 `not_connected`). Send them to `connectUrl`. */
+declare class PipeNotConnectedError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/**
+ * The provider stopped accepting the connection — revoked, or the refresh token expired
+ * (409 `reauthorization_required`). Send the person to `connectUrl` to connect again.
+ */
+declare class PipeReauthorizationRequiredError extends PipeLeaseError {
+    readonly connectUrl: string;
+}
+/** The provider could not refresh the token just now (503). Retry after `retryAfter`. */
+declare class PipeTemporarilyUnavailableError extends PipeLeaseError {
+}
+/**
+ * The lease was denied (403 `lease_denied`): the app is not granted the pipe, the pipe is
+ * disabled or missing, the person is not in the app's organization, or `userId` names
+ * someone other than the token's person. One answer for every reason, by design.
+ */
+declare class PipeLeaseDeniedError extends PipeLeaseError {
+}
 interface StoreSecretInput {
     name: string;
     provider: string;
@@ -54,8 +147,32 @@ declare class VaultClient {
      * is identified by the token's client; a lease with no live grant is refused.
      */
     lease(secretId: string, purpose: string): Promise<VaultLease>;
+    /**
+     * Lease a fresh access token for a person's connected account at `provider` (Pipes,
+     * scope `vault.lease`). The token is refreshed first when it is about to expire, so
+     * you never handle a refresh token.
+     *
+     * With a client-credentials token, name the person in `userId`. With a token issued to
+     * your app FOR a person, leave it out — the lease is theirs.
+     *
+     * ```ts
+     * try {
+     *   const { accessToken } = await vault.leasePipeToken('github', { userId, purpose: 'list-repos' })
+     * } catch (e) {
+     *   if (e instanceof PipeNotConnectedError || e instanceof PipeReauthorizationRequiredError) {
+     *     return redirect(e.connectUrlWith({ clientId, returnTo }))
+     *   }
+     *   throw e
+     * }
+     * ```
+     */
+    leasePipeToken(provider: PipeProvider | string, options: {
+        purpose: string;
+        userId?: string;
+    }): Promise<PipeToken>;
     private json;
     private request;
+    private send;
 }
 
 /**
@@ -259,6 +376,13 @@ declare class CboxIdClient {
      * registered. `organization` picks which of the person's organizations the keys act in;
      * omitted, the page uses the one they are in.
      */
+    /**
+     * The hosted page where the signed-in person connects their account at `provider`
+     * (Pipes) — `/account/connected-services/{provider}/connect`, preselected to this app.
+     * They come back to `returnTo` with `?provider=…&status=connected|cancelled|failed`,
+     * honoured only on an origin the app registered.
+     */
+    pipeConnectUrl(provider: PipeProvider | string, returnTo?: string): string;
     apiKeysUrl(options?: {
         clientId?: string;
         returnTo?: string;
@@ -338,4 +462,4 @@ declare class CboxIdClient {
     private fetchWithTimeout;
 }
 
-export { CboxIdClient as C, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, type StoredAuthState as b, type VaultLease as c, type VaultSecretRef as d, type VerifyStandardWebhookOptions as e, type VerifyWebhookOptions as f, verifyWebhook as g, verifyStandardWebhook as v };
+export { CboxIdClient as C, type PipeConnectOptions as P, type StoreSecretInput as S, VaultClient as V, type WebhookHeaders as W, type CallbackParams as a, PipeLeaseDeniedError as b, PipeLeaseError as c, PipeNotConnectedError as d, type PipeProvider as e, PipeReauthorizationRequiredError as f, PipeTemporarilyUnavailableError as g, type PipeToken as h, type StoredAuthState as i, type VaultLease as j, type VaultSecretRef as k, type VerifyStandardWebhookOptions as l, type VerifyWebhookOptions as m, verifyWebhook as n, pipeConnectUrl as p, verifyStandardWebhook as v, withConnectReturn as w };

package/dist/decisions-C84Fzah4.d.ts

@@ -0,0 +1,23 @@
+import { O as OrganizationRole } from './types-CC1bz68x.js';
+
+interface PermissionDecisionConfig {
+    issuer: string;
+    clientId: string;
+    timeoutMs?: number;
+}
+/** A current server decision; shared membership tiers are not app grants. */
+declare class PermissionDecision {
+    readonly subject: string;
+    readonly organization: string | null;
+    readonly clientId: string;
+    readonly organizationRole: OrganizationRole | null;
+    readonly organizationActive: boolean;
+    readonly permissions: Readonly<Record<string, boolean>>;
+    constructor(subject: string, organization: string | null, clientId: string, organizationRole: OrganizationRole | null, organizationActive: boolean, permissions: Readonly<Record<string, boolean>>);
+    allows(permission: string): boolean;
+    allowed(): boolean;
+}
+/** No positive cache: check each request and again when queued work starts. */
+declare function checkPermissions(config: PermissionDecisionConfig, accessToken: string, subject: string, organization: string | null, permissions: readonly string[]): Promise<PermissionDecision>;
+
+export { PermissionDecision as P, type PermissionDecisionConfig as a, checkPermissions as c };

package/dist/decisions-DNd9UXwi.d.cts

@@ -0,0 +1,23 @@
+import { O as OrganizationRole } from './types-CC1bz68x.cjs';
+
+interface PermissionDecisionConfig {
+    issuer: string;
+    clientId: string;
+    timeoutMs?: number;
+}
+/** A current server decision; shared membership tiers are not app grants. */
+declare class PermissionDecision {
+    readonly subject: string;
+    readonly organization: string | null;
+    readonly clientId: string;
+    readonly organizationRole: OrganizationRole | null;
+    readonly organizationActive: boolean;
+    readonly permissions: Readonly<Record<string, boolean>>;
+    constructor(subject: string, organization: string | null, clientId: string, organizationRole: OrganizationRole | null, organizationActive: boolean, permissions: Readonly<Record<string, boolean>>);
+    allows(permission: string): boolean;
+    allowed(): boolean;
+}
+/** No positive cache: check each request and again when queued work starts. */
+declare function checkPermissions(config: PermissionDecisionConfig, accessToken: string, subject: string, organization: string | null, permissions: readonly string[]): Promise<PermissionDecision>;
+
+export { PermissionDecision as P, type PermissionDecisionConfig as a, checkPermissions as c };