@faable/auth-sdk 2.6.23 → 2.7.0

package/dist/FaableAuthApi.js

@@ -1,5 +1,5 @@
 import { getDomain, isPlainObject, requireId } from "./helpers.js";
-import { FaableApiError } from "./error_handler.js";
+import { FaableApiError } from "@faable/sdk-base";
 import { GeneratedFaableAuthApi } from "./api/generated-client.js";
 import { authClientCredentials } from "@faable/sdk-base";
 import { SDK_CLIENT } from "./version.js";

package/dist/api/generated-client.d.ts

@@ -22,6 +22,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /account` — operationId: `account/create`
      *
      * Create an Account
+     *
+     * Creates a new Auth Account. The slug is derived from the name and used to build the default `*.auth.faable.link` domain.
      */
     accountCreate(data: OpBody<"account/create">): Promise<{
         id: string;
@@ -84,6 +86,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /account/current` — operationId: `account/current`
      *
      * Get current Account
+     *
+     * Returns the Account resolved from request context (header, hostname, or team id). Use `expand` to populate nested references.
      */
     accountCurrent(params?: OpQuery<"account/current">): Promise<{
         id: string;
@@ -146,12 +150,16 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `DELETE /account/{account_id}` — operationId: `account/delete`
      *
      * Delete an Account
+     *
+     * Permanently removes an Account and its associated data. This action cannot be undone.
      */
     accountDelete(account_id: string): Promise<never>;
     /**
      * `GET /account/{account_id}` — operationId: `account/get`
      *
      * Get an Account
+     *
+     * Fetch a single Account by its id. Use `expand` to populate id-only fields (e.g. `default_connection`) inline.
      */
     accountGet(account_id: string, params?: OpQuery<"account/get">): Promise<{
         id: string;
@@ -214,6 +222,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /account/keys` — operationId: `account/getKeys`
      *
      * Get Account signing keys info
+     *
+     * Returns metadata for the Account signing keys: the current production kid, the kid queued for next rotation, and all kids currently published in the JWK Set. Does not expose private key material.
      */
     accountGetKeys(): Promise<{
         production_kid: string;
@@ -224,6 +234,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /account` — operationId: `account/list`
      *
      * List Accounts
+     *
+     * List Accounts owned by the requesting project/team. Supports cursor pagination and `expand`.
      */
     accountList(params?: Omit<OpQuery<"account/list">, "cursor" | "next">): {
         all: () => Promise<{
@@ -405,6 +417,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /recovery-channels/capabilities` — operationId: `account/recoveryChannelsCapabilities`
      *
      * Recovery channel capabilities for this tenant
+     *
+     * Which recovery channels the platform can send, whether the plan allows the paid ones, this month's SMS usage against the included amount, and the tenant configuration as resolved. Drives the "Recovery channels" editor in the dashboard.
      */
     accountRecoveryChannelsCapabilities(): Promise<{
         provider: {
@@ -438,6 +452,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /account/keys/rotate` — operationId: `account/rotateKeys`
      *
      * Rotate Account signing keys
+     *
+     * Promotes the queued key to production and generates a fresh queued key. The previously-active key is retained inside the JWK Set so tokens already issued remain verifiable via `/.well-known/jwks.json`.
      */
     accountRotateKeys(data: OpBody<"account/rotateKeys">): Promise<{
         rotated_at: string;
@@ -450,6 +466,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /sdk-health/{account_id}` — operationId: `account/sdk-health`
      *
      * Library health for this account
+     *
+     * Which Faable client libraries this account is being called with, at which versions, and how far behind the latest published release each one is. Versions are observed from the `x-faable-client` header, so an integration that talks raw OIDC shows up only in the traffic breakdown.
      */
     accountSdkHealth(account_id: string): Promise<{
         libraries: {
@@ -484,6 +502,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /account/{account_id}` — operationId: `account/update`
      *
      * Update an Account
+     *
+     * Update the Account configuration such as branding (logo and icon URLs).
      */
     accountUpdate(account_id: string, data: OpBody<"account/update">): Promise<{
         id: string;
@@ -1285,6 +1305,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /client/{client_id}/rotate-secret` — operationId: `client/rotateSecret`
      *
      * Rotate a Client's secret
+     *
+     * Generates a fresh `client_secret` for the given Client and persists it. The previous secret is invalidated immediately — there is no grace period. Returns the full Client; the dashboard must surface the new secret to the admin once. Existing client_credentials / authorization_code integrations using the old secret will start failing at the token endpoint immediately after this call.
      */
     clientRotateSecret(client_id: string): Promise<{
         id: string;
@@ -1821,6 +1843,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /credentials/{credentials_id}/set-password` — operationId: `credentials/setPassword`
      *
      * Set a credential's password
+     *
+     * Sets or rotates the password for a database credential. The previous password is invalidated immediately. Records a `credential.password_changed` audit entry (initiated_by=admin) for traceability. The confirmation email is only sent when an EXISTING password is rotated: setting the first password on a credential that had none is a creation, not a change. The password is never returned.
      */
     credentialsSetPassword(credentials_id: string, data: OpBody<"credentials/setPassword">): Promise<{
         id: string;
@@ -2026,6 +2050,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /customdomain/{customdomain_id}/retry` — operationId: `customdomain/retry`
      *
      * Trigger a domain verification check now
+     *
+     * Forces an immediate DNS re-check of a Custom Domain in any state. Rate-limited to one check per minute. A verified (ACTIVE) domain stays ACTIVE while it is re-checked; any other state moves to VERIFYING.
      */
     customdomainRetry(customdomain_id: string): Promise<void>;
     /**
@@ -2098,6 +2124,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /identity/{identity_id}/provider-token` — operationId: `identity/getProviderToken`
      *
      * Get a guaranteed-valid provider access_token
+     *
+     * Returns the identity's upstream provider `access_token`, refreshing it transparently via the stored `refresh_token` when it is (about to be) expired. Pass `?fresh=true` to force a refresh. Fails with 400 when the token is expired and no `refresh_token` is available (the user must re-authorize).
      */
     identityGetProviderToken(identity_id: string, params?: OpQuery<"identity/getProviderToken">): Promise<{
         access_token: string;
@@ -2169,6 +2197,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /internal/usage/sms` — operationId: `internal/smsUsage`
      *
      * SMS sent per tenant in a month (platform)
+     *
+     * Per-account count of recovery/verification SMS sent in the given month, read from the monthly quota counters. Consumed by the billing usage job. Platform token with `read:usage`.
      */
     internalSmsUsage(params?: OpQuery<"internal/smsUsage">): Promise<{
         month: string;
@@ -2710,6 +2740,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /loginflow/materialize` — operationId: `loginflow/materialize`
      *
      * Start a custom flow from what runs today
+     *
+     * Creates a login flow whose draft is the graph the account (or, with `client_id`, that client) currently runs — compiled from its settings — and binds it. Nothing changes for logins until the flow is published: a bound flow with no published graph keeps running the compiled one. Never a blank canvas: customising always starts from the tenant's own behaviour.
      */
     loginflowMaterialize(data: OpBody<"loginflow/materialize">): Promise<{
         id: string;
@@ -2783,6 +2815,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /loginflow/{loginflow_id}/preview-token` — operationId: `loginflow/previewToken`
      *
      * Try the draft on a real login, in your browser only
+     *
+     * Returns a short-lived token. Open `/authorize?…&flow_preview=<token>` (or the hosted login with the same parameter) and that login runs the DRAFT of this flow instead of what is published, for that browser only. Nothing is published.
      */
     loginflowPreviewToken(loginflow_id: string): Promise<{
         token: string;
@@ -2792,6 +2826,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /loginflow/{loginflow_id}/publish` — operationId: `loginflow/publish`
      *
      * Make the draft the graph logins run
+     *
+     * Validates the draft and freezes it as `published` under its current revision; the previous published graph moves to `history`. Logins already in flight keep the revision they started on. Refused with the list of issues when the draft does not validate.
      */
     loginflowPublish(loginflow_id: string, data: OpBody<"loginflow/publish">): Promise<{
         id: string;
@@ -2865,6 +2901,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /loginflow/resolved` — operationId: `loginflow/resolved`
      *
      * The graph this account (or client) runs right now
+     *
+     * What a login actually walks: the published graph of the bound flow, or the graph compiled from the settings when nothing is bound or published. With `client_id`, resolved for that client (its own flow, else the account's, else compiled from its overrides). The bound flow, if any, comes along with its draft so an editor can show both.
      */
     loginflowResolved(params?: OpQuery<"loginflow/resolved">): Promise<{
         source: "compiled" | "published";
@@ -2917,6 +2955,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /loginflow/{loginflow_id}/rollback` — operationId: `loginflow/rollback`
      *
      * Run a previously published revision again
+     *
+     * Makes the named revision from `history` the published graph; the one being replaced moves to `history`. The draft is not touched.
      */
     loginflowRollback(loginflow_id: string, data: OpBody<"loginflow/rollback">): Promise<{
         id: string;
@@ -3564,6 +3604,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /team/{team_id}/member` — operationId: `team/addMembers`
      *
      * Add Users to a Team
+     *
+     * Adds one or more Users as members of the given Team. Returns the resulting TeamMember record.
      */
     teamAddMembers(team_id: string, data: OpBody<"team/addMembers">): Promise<{
         id: string;
@@ -3581,6 +3623,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /team/{team_id}/member/check/{user_id}` — operationId: `team/checkMember`
      *
      * Check User is member of a Team
+     *
+     * Returns the TeamMember record if the User belongs to the given Team, or 404 otherwise.
      */
     teamCheckMember(team_id: string, user_id: string, params?: OpQuery<"team/checkMember">): Promise<{
         id: string;
@@ -3652,6 +3696,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /team/{team_id}/invite` — operationId: `team/invite`
      *
      * Invite a user to a Team by email
+     *
+     * Invites a user by email. `mode='auto'` (default) adds the user directly when the email already corresponds to a user in this tenant and falls back to a ticketed invite + email otherwise. `mode='invite'` always issues a ticket + email even when the user exists. Re-inviting the same email to the same team invalidates the previous pending invite.
      */
     teamInvite(team_id: string, data: OpBody<"team/invite">): Promise<{
         status: "invited" | "added";
@@ -3722,6 +3768,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /team/{team_id}/invite` — operationId: `team/listInvites`
      *
      * List pending invites for a Team
+     *
+     * Returns all pending (not consumed, not expired) team invites for the given team. Accepts a FaableQL `query` parameter on the `email` field.
      */
     teamListInvites(team_id: string, params?: OpQuery<"team/listInvites">): Promise<{
         data: {
@@ -3746,6 +3794,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /team/{team_id}/member` — operationId: `team/listMembers`
      *
      * List Team Members
+     *
+     * List all Users that belong to the given Team in the current Account. Supports `?expand=user,team,roles` to inline referenced rows.
      */
     teamListMembers(team_id: string, params?: Omit<OpQuery<"team/listMembers">, "cursor" | "next">): {
         all: () => Promise<{
@@ -3792,6 +3842,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `DELETE /team/{team_id}/invite/{ticket_id}` — operationId: `team/revokeInvite`
      *
      * Revoke a pending team invite
+     *
+     * Marks a pending team invite as consumed so it can no longer be accepted. Returns 400 if the invite is already consumed and 404 if it does not exist or belongs to a different team.
      */
     teamRevokeInvite(team_id: string, ticket_id: string): Promise<{
         status: "revoked";
@@ -4294,6 +4346,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `GET /user/{user_id}/tickets` — operationId: `user/listTickets`
      *
      * List the tickets issued for a user
+     *
+     * Returns the password-reset / verification / invitation tickets issued for this user, newest first, each with its status and — while it is still usable — the link that was emailed. Intended for handing a recovery link over by another channel when the email does not reach the person. Requires `update:credentials`: the link grants the same account access that setting a password does, and each reveal is recorded in the audit log.
      */
     userListTickets(user_id: string): Promise<{
         results: {
@@ -4312,6 +4366,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /user/{user_id}/password-setup` — operationId: `user/passwordSetup`
      *
      * Send a password setup / reset email to the user
+     *
+     * Ensures the user has a database credential (provisioning a password-less one when missing, e.g. for users created via the management API) and creates a `changepassword` ticket, sending the standard password reset email. The link lands on the tenant's auth domain. Idempotent on the credential; each call emits a fresh ticket.
      */
     userPasswordSetup(user_id: string, data: OpBody<"user/passwordSetup">): Promise<{
         status: "sent";
@@ -4323,6 +4379,8 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
      * `POST /user/{user_id}/tickets/{ticket_id}/revoke` — operationId: `user/revokeTicket`
      *
      * Revoke a ticket issued for a user
+     *
+     * Marks the ticket as consumed so its link stops working immediately. The counterpart of listing links: once a link has been copied out of the dashboard it can end up in the wrong chat window, and the TTL alone is too slow an answer.
      */
     userRevokeTicket(user_id: string, ticket_id: string): Promise<{
         status: "revoked" | "already_used";

package/dist/api/generated-client.js

@@ -13,6 +13,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /account` — operationId: `account/create`
      *
      * Create an Account
+     *
+     * Creates a new Auth Account. The slug is derived from the name and used to build the default `*.auth.faable.link` domain.
      */
     accountCreate(data) {
         return this.fetcher.post(`/account`, data);
@@ -21,6 +23,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /account/current` — operationId: `account/current`
      *
      * Get current Account
+     *
+     * Returns the Account resolved from request context (header, hostname, or team id). Use `expand` to populate nested references.
      */
     accountCurrent(params) {
         return this.fetcher.request({ method: "GET", url: `/account/current`, params });
@@ -29,6 +33,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `DELETE /account/{account_id}` — operationId: `account/delete`
      *
      * Delete an Account
+     *
+     * Permanently removes an Account and its associated data. This action cannot be undone.
      */
     accountDelete(account_id) {
         requireId("account_id", account_id);
@@ -38,6 +44,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /account/{account_id}` — operationId: `account/get`
      *
      * Get an Account
+     *
+     * Fetch a single Account by its id. Use `expand` to populate id-only fields (e.g. `default_connection`) inline.
      */
     accountGet(account_id, params) {
         requireId("account_id", account_id);
@@ -47,6 +55,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /account/keys` — operationId: `account/getKeys`
      *
      * Get Account signing keys info
+     *
+     * Returns metadata for the Account signing keys: the current production kid, the kid queued for next rotation, and all kids currently published in the JWK Set. Does not expose private key material.
      */
     accountGetKeys() {
         return this.fetcher.get(`/account/keys`);
@@ -55,6 +65,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /account` — operationId: `account/list`
      *
      * List Accounts
+     *
+     * List Accounts owned by the requesting project/team. Supports cursor pagination and `expand`.
      */
     accountList(params) {
         return this.paginator({ url: `/account`, params });
@@ -63,6 +75,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /recovery-channels/capabilities` — operationId: `account/recoveryChannelsCapabilities`
      *
      * Recovery channel capabilities for this tenant
+     *
+     * Which recovery channels the platform can send, whether the plan allows the paid ones, this month's SMS usage against the included amount, and the tenant configuration as resolved. Drives the "Recovery channels" editor in the dashboard.
      */
     accountRecoveryChannelsCapabilities() {
         return this.fetcher.get(`/recovery-channels/capabilities`);
@@ -71,6 +85,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /account/keys/rotate` — operationId: `account/rotateKeys`
      *
      * Rotate Account signing keys
+     *
+     * Promotes the queued key to production and generates a fresh queued key. The previously-active key is retained inside the JWK Set so tokens already issued remain verifiable via `/.well-known/jwks.json`.
      */
     accountRotateKeys(data) {
         return this.fetcher.post(`/account/keys/rotate`, data);
@@ -79,6 +95,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /sdk-health/{account_id}` — operationId: `account/sdk-health`
      *
      * Library health for this account
+     *
+     * Which Faable client libraries this account is being called with, at which versions, and how far behind the latest published release each one is. Versions are observed from the `x-faable-client` header, so an integration that talks raw OIDC shows up only in the traffic breakdown.
      */
     accountSdkHealth(account_id) {
         requireId("account_id", account_id);
@@ -88,6 +106,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /account/{account_id}` — operationId: `account/update`
      *
      * Update an Account
+     *
+     * Update the Account configuration such as branding (logo and icon URLs).
      */
     accountUpdate(account_id, data) {
         requireId("account_id", account_id);
@@ -217,6 +237,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /client/{client_id}/rotate-secret` — operationId: `client/rotateSecret`
      *
      * Rotate a Client's secret
+     *
+     * Generates a fresh `client_secret` for the given Client and persists it. The previous secret is invalidated immediately — there is no grace period. Returns the full Client; the dashboard must surface the new secret to the admin once. Existing client_credentials / authorization_code integrations using the old secret will start failing at the token endpoint immediately after this call.
      */
     clientRotateSecret(client_id) {
         requireId("client_id", client_id);
@@ -312,6 +334,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /credentials/{credentials_id}/set-password` — operationId: `credentials/setPassword`
      *
      * Set a credential's password
+     *
+     * Sets or rotates the password for a database credential. The previous password is invalidated immediately. Records a `credential.password_changed` audit entry (initiated_by=admin) for traceability. The confirmation email is only sent when an EXISTING password is rotated: setting the first password on a credential that had none is a creation, not a change. The password is never returned.
      */
     credentialsSetPassword(credentials_id, data) {
         requireId("credentials_id", credentials_id);
@@ -364,6 +388,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /customdomain/{customdomain_id}/retry` — operationId: `customdomain/retry`
      *
      * Trigger a domain verification check now
+     *
+     * Forces an immediate DNS re-check of a Custom Domain in any state. Rate-limited to one check per minute. A verified (ACTIVE) domain stays ACTIVE while it is re-checked; any other state moves to VERIFYING.
      */
     customdomainRetry(customdomain_id) {
         requireId("customdomain_id", customdomain_id);
@@ -399,6 +425,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /identity/{identity_id}/provider-token` — operationId: `identity/getProviderToken`
      *
      * Get a guaranteed-valid provider access_token
+     *
+     * Returns the identity's upstream provider `access_token`, refreshing it transparently via the stored `refresh_token` when it is (about to be) expired. Pass `?fresh=true` to force a refresh. Fails with 400 when the token is expired and no `refresh_token` is available (the user must re-authorize).
      */
     identityGetProviderToken(identity_id, params) {
         requireId("identity_id", identity_id);
@@ -416,6 +444,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /internal/usage/sms` — operationId: `internal/smsUsage`
      *
      * SMS sent per tenant in a month (platform)
+     *
+     * Per-account count of recovery/verification SMS sent in the given month, read from the monthly quota counters. Consumed by the billing usage job. Platform token with `read:usage`.
      */
     internalSmsUsage(params) {
         return this.fetcher.request({ method: "GET", url: `/internal/usage/sms`, params });
@@ -475,6 +505,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /loginflow/materialize` — operationId: `loginflow/materialize`
      *
      * Start a custom flow from what runs today
+     *
+     * Creates a login flow whose draft is the graph the account (or, with `client_id`, that client) currently runs — compiled from its settings — and binds it. Nothing changes for logins until the flow is published: a bound flow with no published graph keeps running the compiled one. Never a blank canvas: customising always starts from the tenant's own behaviour.
      */
     loginflowMaterialize(data) {
         return this.fetcher.post(`/loginflow/materialize`, data);
@@ -483,6 +515,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /loginflow/{loginflow_id}/preview-token` — operationId: `loginflow/previewToken`
      *
      * Try the draft on a real login, in your browser only
+     *
+     * Returns a short-lived token. Open `/authorize?…&flow_preview=<token>` (or the hosted login with the same parameter) and that login runs the DRAFT of this flow instead of what is published, for that browser only. Nothing is published.
      */
     loginflowPreviewToken(loginflow_id) {
         requireId("loginflow_id", loginflow_id);
@@ -492,6 +526,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /loginflow/{loginflow_id}/publish` — operationId: `loginflow/publish`
      *
      * Make the draft the graph logins run
+     *
+     * Validates the draft and freezes it as `published` under its current revision; the previous published graph moves to `history`. Logins already in flight keep the revision they started on. Refused with the list of issues when the draft does not validate.
      */
     loginflowPublish(loginflow_id, data) {
         requireId("loginflow_id", loginflow_id);
@@ -501,6 +537,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /loginflow/resolved` — operationId: `loginflow/resolved`
      *
      * The graph this account (or client) runs right now
+     *
+     * What a login actually walks: the published graph of the bound flow, or the graph compiled from the settings when nothing is bound or published. With `client_id`, resolved for that client (its own flow, else the account's, else compiled from its overrides). The bound flow, if any, comes along with its draft so an editor can show both.
      */
     loginflowResolved(params) {
         return this.fetcher.request({ method: "GET", url: `/loginflow/resolved`, params });
@@ -509,6 +547,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /loginflow/{loginflow_id}/rollback` — operationId: `loginflow/rollback`
      *
      * Run a previously published revision again
+     *
+     * Makes the named revision from `history` the published graph; the one being replaced moves to `history`. The draft is not touched.
      */
     loginflowRollback(loginflow_id, data) {
         requireId("loginflow_id", loginflow_id);
@@ -674,6 +714,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /team/{team_id}/member` — operationId: `team/addMembers`
      *
      * Add Users to a Team
+     *
+     * Adds one or more Users as members of the given Team. Returns the resulting TeamMember record.
      */
     teamAddMembers(team_id, data) {
         requireId("team_id", team_id);
@@ -683,6 +725,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /team/{team_id}/member/check/{user_id}` — operationId: `team/checkMember`
      *
      * Check User is member of a Team
+     *
+     * Returns the TeamMember record if the User belongs to the given Team, or 404 otherwise.
      */
     teamCheckMember(team_id, user_id, params) {
         requireId("team_id", team_id);
@@ -719,6 +763,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /team/{team_id}/invite` — operationId: `team/invite`
      *
      * Invite a user to a Team by email
+     *
+     * Invites a user by email. `mode='auto'` (default) adds the user directly when the email already corresponds to a user in this tenant and falls back to a ticketed invite + email otherwise. `mode='invite'` always issues a ticket + email even when the user exists. Re-inviting the same email to the same team invalidates the previous pending invite.
      */
     teamInvite(team_id, data) {
         requireId("team_id", team_id);
@@ -736,6 +782,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /team/{team_id}/invite` — operationId: `team/listInvites`
      *
      * List pending invites for a Team
+     *
+     * Returns all pending (not consumed, not expired) team invites for the given team. Accepts a FaableQL `query` parameter on the `email` field.
      */
     teamListInvites(team_id, params) {
         requireId("team_id", team_id);
@@ -745,6 +793,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /team/{team_id}/member` — operationId: `team/listMembers`
      *
      * List Team Members
+     *
+     * List all Users that belong to the given Team in the current Account. Supports `?expand=user,team,roles` to inline referenced rows.
      */
     teamListMembers(team_id, params) {
         requireId("team_id", team_id);
@@ -754,6 +804,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `DELETE /team/{team_id}/invite/{ticket_id}` — operationId: `team/revokeInvite`
      *
      * Revoke a pending team invite
+     *
+     * Marks a pending team invite as consumed so it can no longer be accepted. Returns 400 if the invite is already consumed and 404 if it does not exist or belongs to a different team.
      */
     teamRevokeInvite(team_id, ticket_id) {
         requireId("team_id", team_id);
@@ -841,6 +893,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `GET /user/{user_id}/tickets` — operationId: `user/listTickets`
      *
      * List the tickets issued for a user
+     *
+     * Returns the password-reset / verification / invitation tickets issued for this user, newest first, each with its status and — while it is still usable — the link that was emailed. Intended for handing a recovery link over by another channel when the email does not reach the person. Requires `update:credentials`: the link grants the same account access that setting a password does, and each reveal is recorded in the audit log.
      */
     userListTickets(user_id) {
         requireId("user_id", user_id);
@@ -850,6 +904,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /user/{user_id}/password-setup` — operationId: `user/passwordSetup`
      *
      * Send a password setup / reset email to the user
+     *
+     * Ensures the user has a database credential (provisioning a password-less one when missing, e.g. for users created via the management API) and creates a `changepassword` ticket, sending the standard password reset email. The link lands on the tenant's auth domain. Idempotent on the credential; each call emits a fresh ticket.
      */
     userPasswordSetup(user_id, data) {
         requireId("user_id", user_id);
@@ -859,6 +915,8 @@ export class GeneratedFaableAuthApi extends FaableApi {
      * `POST /user/{user_id}/tickets/{ticket_id}/revoke` — operationId: `user/revokeTicket`
      *
      * Revoke a ticket issued for a user
+     *
+     * Marks the ticket as consumed so its link stops working immediately. The counterpart of listing links: once a link has been copied out of the dashboard it can end up in the wrong chat window, and the TTL alone is too slow an answer.
      */
     userRevokeTicket(user_id, ticket_id) {
         requireId("user_id", user_id);

package/dist/helpers.js

@@ -1,4 +1,4 @@
-import { FaableApiError } from "./error_handler.js";
+import { FaableApiError } from "@faable/sdk-base";
 // Normaliza el `domain` para que dé igual cómo lo pase el usuario: con o sin
 // protocolo, con trailing slash, o incluso con protocolo duplicado (el valor
 // que el dashboard copia ya trae `https://`). Siempre devuelve

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export { SDK_CLIENT, commit, version } from "./version.js";
 export * from "./api/generated-client.js";
 export * from "./api/api-types.js";
 export * from "./api/types.js";
-export { authClientCredentials, authApikey, authBearer, authCookie, } from "@faable/sdk-base";
+export { authClientCredentials, authApikey, authBearer, authCookie, FaableApiError, } from "@faable/sdk-base";
 export type { ApiParams, ClientCredentialsConfig, ApikeyConfig, BearerConfig, RetryConfig, Fetcher, FetcherConfig, FetcherRequestParams, AuthStrategy, AuthStrategyBuilder, AuthStrategyContext, } from "@faable/sdk-base";

package/dist/index.js

@@ -6,4 +6,8 @@ export * from "./api/types.js";
 // Re-export the auth strategies (and their config/types) from
 // @faable/sdk-base so consumers depend on @faable/auth-sdk ONLY — sdk-base
 // stays a transitive dependency and no app needs to import it directly.
-export { authClientCredentials, authApikey, authBearer, authCookie, } from "@faable/sdk-base";
+export { authClientCredentials, authApikey, authBearer, authCookie, 
+// The error every method throws on a non-2xx. Branch on `err.error_code`
+// (or `err.isErrorCode('sms_unavailable')`), never on `err.message`: the
+// generated client lists the codes of each method as `@throws`.
+FaableApiError, } from "@faable/sdk-base";

package/dist/version.js

@@ -9,13 +9,13 @@
 // login pages could not import the SDK at all. Same pattern as auth-js.
 //
 // The sentinels MUST stay byte-identical to the `from` values in `.releaserc`.
-export const version = "2.6.23";
+export const version = "2.7.0";
 // Short git SHA of the released commit. The version dates a build; this names
 // the exact tree, so a canonical log line or an audit entry leads straight to
 // `git show <sha>`. Deliberately NOT hex: an unreleased build (dev, a local
 // link) cannot be mistaken for a real commit — auth only records values that
 // look like a SHA, and this one never will.
-export const commit = "65b2a2d";
+export const commit = "7ef7d78";
 // What this SDK writes in `x-faable-client`. Exported for a consumer that
 // builds a strategy on its own (outside `FaableAuthApi`) and still wants the
 // token request attributed — a bare `authClientCredentials` stamps only what

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/auth-sdk",
-  "version": "2.6.23",
+  "version": "2.7.0",
   "author": "Marc Pomar <marc@faable.com>",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,7 @@
   },
   "type": "module",
   "dependencies": {
-    "@faable/sdk-base": "^1.6.0"
+    "@faable/sdk-base": "^1.7.0"
   },
   "devDependencies": {
     "@ava/typescript": "^5.0.0",

package/scripts/gen-client.mjs

@@ -80,6 +80,40 @@ for (const [path, methods] of Object.entries(spec.paths || {})) {
 }
 operations.sort((a, b) => a.op.operationId.localeCompare(b.op.operationId));
 
+// Multi-line descriptions become one JSDoc line each.
+const escapeBlock = (text) =>
+  String(text)
+    .split("\n")
+    .map((l) => `   * ${escape(l)}`);
+
+// The server documents each 4xx/5xx as an ErrorResponse whose `error_code`
+// is restricted to an enum, and describes every code in the response
+// description as "`code` — text" lines. Read both back so the docstring can
+// list what a caller may branch on.
+const errorCodesOf = (op) => {
+  const out = [];
+  const seen = new Set();
+  for (const [status, res] of Object.entries(op.responses || {})) {
+    if (!/^[45]\d\d$/.test(status)) continue;
+    const schema = res?.content?.["application/json"]?.schema;
+    const parts = schema?.allOf || (schema ? [schema] : []);
+    const codes = parts.flatMap((p) => p?.properties?.error_code?.enum || []);
+    const descriptions = new Map(
+      String(res?.description || "")
+        .split("\n")
+        .map((l) => l.match(/^`([a-z_]+)` — (.*)$/))
+        .filter(Boolean)
+        .map((m) => [m[1], m[2]]),
+    );
+    for (const code of codes) {
+      if (seen.has(code)) continue;
+      seen.add(code);
+      out.push({ code, status, description: descriptions.get(code) });
+    }
+  }
+  return out;
+};
+
 const emitMethod = ({ path, httpMethod, op }) => {
   const id = op.operationId;
   const name = toMethodName(id);
@@ -128,11 +162,23 @@ const emitMethod = ({ path, httpMethod, op }) => {
   }
 
   const guards = pathParams.map((p) => `    requireId("${p}", ${p});`);
-  const doc = op.summary || op.description;
+  // Summary AND description: the CRUD summaries are generic ("Get User") and
+  // used to hide the prose that actually explains the endpoint.
+  const docLines = [op.summary, op.description]
+    .filter((x, i, all) => x && all.indexOf(x) === i)
+    .flatMap((text, i) => [...(i ? ["   *"] : []), ...escapeBlock(text)]);
+  // One `@throws` per documented error code, read from the 4xx/5xx responses
+  // the server injects (see auth's server/openapi_errors.ts). The code is
+  // `err.error_code` on the FaableApiError the fetcher throws.
+  const throwsLines = errorCodesOf(op).map(
+    ({ code, status, description }) =>
+      `   * @throws {FaableApiError} \`${code}\` (${status})${description ? ` — ${escape(description)}` : ""}`,
+  );
   const jsdoc = [
     "  /**",
     `   * \`${httpMethod.toUpperCase()} ${path}\` — operationId: \`${id}\``,
-    ...(doc ? [`   *`, `   * ${escape(doc)}`] : []),
+    ...(docLines.length ? ["   *", ...docLines] : []),
+    ...(throwsLines.length ? ["   *", ...throwsLines] : []),
     "   */",
   ].join("\n");
 

package/dist/error_handler.d.ts

@@ -1,27 +0,0 @@
-import type { AxiosError } from "axios";
-/**
- * El error que lanza el SDK cuando la API responde con un fallo.
- *
- * ⚠️ **`error_code` es la parte con la que se ramifica, no el mensaje.** El
- * `message` de la API está escrito para que lo lea una persona y puede cambiar
- * —de hecho cambia: el de teléfono inválido se reescribió el 17-09 para que se
- * entendiera en el formulario de un tenant que lo pintaba literal—. Hasta esa
- * fecha este error aplanaba la respuesta en un string y se llevaba por delante
- * el `error_code`, así que quien integraba no tenía más remedio que comparar
- * textos en inglés. Ahora viajan también `status`, `error_code` y el cuerpo
- * entero.
- */
-export declare class FaableApiError extends Error {
-    /** Código HTTP de la respuesta, cuando la hubo. */
-    readonly status?: number;
-    /** Código estable del error (`invalid_phone`, `sms_unavailable:plan`, …). */
-    readonly error_code?: string;
-    /** Cuerpo de la respuesta tal cual, por si hace falta algo más. */
-    readonly body?: unknown;
-    constructor(msg: string, details?: {
-        status?: number;
-        error_code?: string;
-        body?: unknown;
-    });
-}
-export declare const handleErrorInterceptor: (e: AxiosError) => Promise<never>;

package/dist/error_handler.js

@@ -1,36 +0,0 @@
-/**
- * El error que lanza el SDK cuando la API responde con un fallo.
- *
- * ⚠️ **`error_code` es la parte con la que se ramifica, no el mensaje.** El
- * `message` de la API está escrito para que lo lea una persona y puede cambiar
- * —de hecho cambia: el de teléfono inválido se reescribió el 17-09 para que se
- * entendiera en el formulario de un tenant que lo pintaba literal—. Hasta esa
- * fecha este error aplanaba la respuesta en un string y se llevaba por delante
- * el `error_code`, así que quien integraba no tenía más remedio que comparar
- * textos en inglés. Ahora viajan también `status`, `error_code` y el cuerpo
- * entero.
- */
-export class FaableApiError extends Error {
-    /** Código HTTP de la respuesta, cuando la hubo. */
-    status;
-    /** Código estable del error (`invalid_phone`, `sms_unavailable:plan`, …). */
-    error_code;
-    /** Cuerpo de la respuesta tal cual, por si hace falta algo más. */
-    body;
-    constructor(msg, details = {}) {
-        super(msg);
-        this.name = "FaableApiError";
-        this.status = details.status;
-        this.error_code = details.error_code;
-        this.body = details.body;
-        Object.setPrototypeOf(this, FaableApiError.prototype);
-    }
-}
-export const handleErrorInterceptor = async (e) => {
-    const data = e.response?.data;
-    throw new FaableApiError(`FaableApiError: ${data?.message} (status=${e.response?.status}, url=${e.response?.config.url})`, {
-        status: e.response?.status,
-        error_code: data?.error_code,
-        body: data
-    });
-};