@babelforce/manager-sdk 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to `@babelforce/manager-sdk` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## 0.40.0
+
+- Added first-class **Authorization Code + PKCE** (RFC 7636) support: a new `refreshToken` auth mode
+  (transparent refresh with refresh-token rotation) plus the helpers `pkceChallenge`,
+  `buildAuthorizeUrl`, `authorizationCodeGrant`, and `refreshTokenGrant`. `clientCredentialsGrant` is
+  now exported too. `TokenResponse` gained an optional `refresh_token`.
+- Consolidated the docs: the OAuth guide is merged into a single **Authentication** guide (overview +
+  one section per flow + when-to-use). Client credentials is documented with a security-review/limited-
+  availability caveat.
+
 ## 0.39.0
 
 - Refreshed the vendored manager API spec (richer endpoint descriptions/examples) and regenerated

package/README.md

@@ -37,10 +37,14 @@ await mgr.users.enable(["new.user@acme.com"]);
 
 ### Authentication
 
-- `{ kind: "clientCredentials", clientId, clientSecret }` — recommended for server-to-server use;
-  OAuth2 client_credentials grant against `/oauth/token` with transparent refresh.
+- `{ kind: "refreshToken", refreshToken, clientId }` — a refresh token from the Authorization Code +
+  PKCE flow (helpers: `pkceChallenge`, `buildAuthorizeUrl`, `authorizationCodeGrant`); transparent
+  refresh with rotation. Best for apps acting on behalf of a user.
+- `{ kind: "clientCredentials", clientId, clientSecret }` — OAuth2 client_credentials grant with
+  transparent refresh, for server-to-server use (credential issuance is in security review — see the
+  [Authentication guide](https://babelforce.github.io/manager-sdk/guides/authentication)).
 - `{ kind: "bearer", token }` — a token you already hold.
-- `{ kind: "password", user, pass }` — OAuth2 password grant with transparent refresh.
+- `{ kind: "password", user, pass }` — OAuth2 password grant (legacy) with transparent refresh.
 
 ### Errors
 

package/dist/index.d.ts

@@ -3,12 +3,17 @@ import { Client } from '@hey-api/client-fetch';
 /**
  * How the SDK authenticates against the manager API.
  *
- * - `clientCredentials` — the recommended server-to-server mode; OAuth2 client_credentials grant
- *   against `/oauth/token`. The token is fetched lazily on the first request and refreshed
- *   transparently before it expires.
- * - `bearer` — a bearer token you already obtained.
+ * - `clientCredentials` — server-to-server OAuth2 client_credentials grant against `/oauth/token`.
+ *   The token is fetched lazily on the first request and refreshed transparently before it expires.
+ *   Requires an OAuth2 application (client id/secret); see the Authentication guide for the current
+ *   availability caveat.
+ * - `bearer` — a bearer token you already obtained (e.g. the access token from a PKCE flow).
  * - `password` — OAuth2 password grant against `/oauth/token`; the token is fetched lazily on the
  *   first request and refreshed transparently before it expires. Convenience for interactive/dev use.
+ * - `refreshToken` — a refresh token obtained from the Authorization Code + PKCE flow. The SDK
+ *   exchanges it for an access token lazily and refreshes transparently, capturing the rotated
+ *   refresh token on each use (refresh tokens are single-use). The recommended way to run a
+ *   long-lived client on behalf of a user.
  */
 type Auth = {
     kind: 'clientCredentials';
@@ -22,12 +27,46 @@ type Auth = {
     user: string;
     pass: string;
     clientId?: string;
+} | {
+    kind: 'refreshToken';
+    refreshToken: string;
+    clientId?: string;
+    clientSecret?: string;
 };
 interface TokenResponse {
     access_token: string;
     expires_in?: number;
     token_type?: string;
+    /** Present for the authorization_code (offline) and refresh_token grants; rotated on every use. */
+    refresh_token?: string;
+}
+interface PkceChallenge {
+    /** The high-entropy secret to keep client-side and send with {@link authorizationCodeGrant}. */
+    codeVerifier: string;
+    /** The base64url(SHA-256(codeVerifier)) value to send with {@link buildAuthorizeUrl}. */
+    codeChallenge: string;
+    codeChallengeMethod: 'S256';
 }
+/**
+ * Generate a PKCE code verifier + S256 challenge (RFC 7636). Pass `codeChallenge` to
+ * {@link buildAuthorizeUrl} and keep `codeVerifier` to later exchange the returned code via
+ * {@link authorizationCodeGrant}. Uses the Web Crypto API (Node 18+ / browsers).
+ */
+declare function pkceChallenge(): Promise<PkceChallenge>;
+interface AuthorizeUrlOptions {
+    baseUrl: string;
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    codeChallenge: string;
+    state?: string;
+    codeChallengeMethod?: 'S256' | 'plain';
+}
+/**
+ * Build the `GET {baseUrl}/oauth/authorize` URL that starts the Authorization Code + PKCE flow.
+ * Redirect the user to it; babelforce redirects back to `redirectUri` with a `code`.
+ */
+declare function buildAuthorizeUrl(opts: AuthorizeUrlOptions): string;
 /**
  * Exchange a username/password for a bearer token via the manager OAuth2 password grant
  * (`POST {baseUrl}/oauth/token`). Exposed for callers who want to manage tokens themselves.
@@ -39,6 +78,42 @@ declare function passwordGrant(opts: {
     clientId?: string;
     fetch?: typeof fetch;
 }): Promise<TokenResponse>;
+/**
+ * Exchange a client id/secret for a bearer token via the manager OAuth2 client_credentials grant
+ * (`POST {baseUrl}/oauth/token`). Exposed for callers who want to manage tokens themselves.
+ */
+declare function clientCredentialsGrant(opts: {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    fetch?: typeof fetch;
+}): Promise<TokenResponse>;
+/**
+ * Exchange an authorization `code` (from the PKCE consent redirect) for tokens via the
+ * authorization_code grant. Public clients pass only `codeVerifier`; confidential clients may also
+ * pass `clientSecret`. Returns an access token and (for offline access) a rotating refresh token.
+ */
+declare function authorizationCodeGrant(opts: {
+    baseUrl: string;
+    code: string;
+    redirectUri: string;
+    clientId: string;
+    codeVerifier: string;
+    clientSecret?: string;
+    fetch?: typeof fetch;
+}): Promise<TokenResponse>;
+/**
+ * Exchange the most-recently-issued refresh token for a fresh token set via the refresh_token grant.
+ * Refresh tokens are rotated on every use — the response carries the next one. Exposed for callers
+ * who want to manage tokens themselves; the `refreshToken` auth mode does this transparently.
+ */
+declare function refreshTokenGrant(opts: {
+    baseUrl: string;
+    refreshToken: string;
+    clientId?: string;
+    clientSecret?: string;
+    fetch?: typeof fetch;
+}): Promise<TokenResponse>;
 
 /**
  * Automatic request retries for the manager SDK.
@@ -7889,4 +7964,4 @@ declare class ManagerApiError extends Error {
     static from(response: Response, body: unknown): ManagerApiError;
 }
 
-export { type Account, type AccountRole$1 as AccountRole, type AddOutboundLeadRequest, type Agent, type AgentGroup, type AgentGroupItemResponse, AgentGroupsResource, type AgentItemResponse, type AgentLineStatus, type AgentLogsQuery, type AgentOutboundCallRequest, type AgentStatus, AgentsResource, AppActionsResource, type Application, type ApplicationCreateBody, type ApplicationItemResponse, type ApplicationUpdateBody, ApplicationsResource, type Auth, AuthResource, type AuthorizeData, AutomationsResource, type Babeldesk, type BabeldeskItemResponse, BabeldeskResource, type BabeldeskWidget, type BabeldeskWidgetItemResponse, BabeldeskWidgetsResource, type BulkActionResponse, type BulkIdsRequest, type BulkUpdateIntegrationsRequest, type BulkUpdateRequest, type BusinessHour, type BusinessHourItemResponse, BusinessHoursResource, type Calendar, type CalendarItemResponse, CalendarsResource, type Call, type CallAttempt, type CallItemResponse, CallsResource, type CampaignHopperResponse, type CampaignItemResponse, type CampaignRealtimeStatusResponse, type CampaignStatisticsResponse, CampaignsResource, type Conference, type ConferenceItemResponse, ConferencesResource, type Conversation, type ConversationEvent, type ConversationItemResponse, type ConversationSessionVariables, ConversationsResource, type CreateCampaignRequest, type CreateListRequest, type CreateManagedUserRequest, type CreateOutboundListRequest, type CreateTestCall, DEFAULT_BASE_URL, type Dashboard, type DashboardCreateBody, type DashboardItemResponse, type DashboardUpdateBody, type DashboardUser, type DashboardUsersResponse, DashboardsResource, type DefaultV2MessageResponse, type DialerBehaviour, type DialerBehaviourItemResponse, type DialerBehaviourWriteBody, DialerBehavioursResource, DialerResource, type DialerSimpleReportingQuery, EventsResource, ExpressionsResource, type FileBulkDeleteRequest, type FileBulkDownloadRequest, FilesResource, type GenericItemResponse, type GlobalAutomation, type GlobalAutomationItemResponse, type ImportAgentsOptions, type Integration, type IntegrationBulkIdsRequest, type IntegrationCreateRequest, type IntegrationItemResponse, type IntegrationObjectListResponse, type IntegrationProvider, type IntegrationTokenItemResponse, type IntegrationTokenListResponse, type IntegrationUpdateRequest, IntegrationsResource, type InterruptionTargetStates, type IvrModule, type Lead, type LeadBulkDeleteRequest, type LeadListItemResponse, type LeadUploadRequest, type LeadUploadResponse, type ListAgentsQuery, type ListApplicationsQuery, type ListAuditLogsQuery, type ListAutomationsQuery, type ListBabeldeskWidgetsQuery, type ListBabeldesksQuery, type ListBusinessHoursQuery, type ListCalendarsQuery, type ListConferencesQuery, type ListConversationsQuery, type ListDashboardsQuery, type ListDialerBehavioursQuery, type ListFilesQuery, type ListIntegrationsQuery, type ListNumbersQuery, type ListOutboundAttemptsQuery, type ListOutboundLeadsQuery, type ListPhonebookQuery, type ListProcessedOutboundLeadsQuery, type ListPromptsQuery, type ListQueuesQuery, type ListRecordingsQuery, type ListRoutingsQuery, type ListSmsQuery, type ListTasksQuery, type ListTriggersQuery, type ListUsersQuery, type LocalAutomation, type LocalAutomationItemResponse, LogsResource, type ManagedUser, type ManagedUserItemResponse, ManagerApiError, ManagerClient, type ManagerClientOptions, MeResource, type MetricDefinitionItemResponse, type MetricIdItemsResponse, type MetricResponse, MetricsResource, NumbersResource, type OAuthRevokeRequest, type OAuthTokenRequest, type OAuthTokenResponse, type ObjectListResponse, type OutboundCampaign, type OutboundCampaignItemResponse, type OutboundLeadItemResponse, type OutboundList, type OutboundListItemResponse, OutboundResource, type OutboundSimpleReportingQuery, type PaginatedAttemptResponse, type PaginatedLeadResponse, type PaginatedRecordingResponse, type PhonebookCsvFile, type PhonebookEntry, type PhonebookEntryItemResponse, PhonebookResource, type Prompt, type PromptAudioFile, type PromptItemResponse, PromptsResource, type Queue, type QueueItemResponse, type QueueSelection, type QueueSelectionItemResponse, QueueSelectionsResource, type QueueTriggerListResponse, QueuesResource, type Recording, type RecordingItemResponse, type RecordingStartRequest, type RecordingState, type RecordingUpdateBody, RecordingsResource, type ReportingCall, type ReportingCallsQuery, ReportingResource, type RestCreateAgentBody, type RestCreateAgentGroupBody, type RestCreateBabeldeskBody, type RestCreateBabeldeskWidgetBody, type RestCreateBusinessHourBody, type RestCreateCalendarBody, type RestCreateConversationBody, type RestCreateGlobalAutomationBody, type RestCreateLocalAutomationBody, type RestCreatePhonebookEntryBody, type RestCreateQueueBody, type RestCreateQueueSelectionBody, type RestCreateRoutingBody, type RestCreateTriggerBody, type RestUpdateAgentBody, type RestUpdateAgentGroupBody, type RestUpdateBabeldeskBody, type RestUpdateBabeldeskWidgetBody, type RestUpdateBusinessHourBody, type RestUpdateCalendarBody, type RestUpdateConversationBody, type RestUpdateGlobalAutomationBody, type RestUpdateLocalAutomationBody, type RestUpdatePhonebookEntryBody, type RestUpdatePromptBody, type RestUpdateQueueBody, type RestUpdateQueueSelectionBody, type RestUpdateRoutingBody, type RestUpdateTriggerBody, type RetryOptions, type Routing, type RoutingItemResponse, RoutingResource, type ServiceNumber, type ServiceNumberItemResponse, type SessionResponse, SessionsResource, type SetCampaignListRequest, SettingAccessor, type SettingsAppAgentStatus, type SettingsAppConversations, type SettingsAppCustomerLogging, type SettingsAppIntegrations, type SettingsAuditDefault, SettingsResource, type SettingsRetentionPeriods, type SettingsTelephonyAgentInbound, type SettingsTelephonyAgentOutbound, type SettingsTelephonyAgentRecording, type SettingsTelephonyAgentWrapup, type SettingsTelephonyPostCall, type SettingsUiI18N, type SimpleReportingCallsQuery, type Sms, type SmsItemResponse, SmsResource, type StorageState, type StorageType, type StoredFile, type StoredFileItemResponse, type SubmitTaskBody, type SubmitTaskScheduleBody, SystemResource, type Tag, type Task, TaskMetricsResource, type TaskSchedule, TaskSchedulesResource, TaskScriptsResource, TaskSecretsResource, TaskSelectionConfigResource, type TaskTemplateOverrides, TasksResource, type TokenResponse, type Trigger, type TriggerConditionListResponse, type TriggerConditionsRequest, type TriggerItemResponse, type TriggerUsesResponse, TriggersResource, type UpdateAgentStatusRequest, type UpdateCampaignRequest, type UpdateSessionVariablesRequest, type UpdateTaskBody, type User, type UserCustomer, type UserCustomerItemResponse, type UserItemResponse, UsersResource, passwordGrant, withRetry };
+export { type Account, type AccountRole$1 as AccountRole, type AddOutboundLeadRequest, type Agent, type AgentGroup, type AgentGroupItemResponse, AgentGroupsResource, type AgentItemResponse, type AgentLineStatus, type AgentLogsQuery, type AgentOutboundCallRequest, type AgentStatus, AgentsResource, AppActionsResource, type Application, type ApplicationCreateBody, type ApplicationItemResponse, type ApplicationUpdateBody, ApplicationsResource, type Auth, AuthResource, type AuthorizeData, type AuthorizeUrlOptions, AutomationsResource, type Babeldesk, type BabeldeskItemResponse, BabeldeskResource, type BabeldeskWidget, type BabeldeskWidgetItemResponse, BabeldeskWidgetsResource, type BulkActionResponse, type BulkIdsRequest, type BulkUpdateIntegrationsRequest, type BulkUpdateRequest, type BusinessHour, type BusinessHourItemResponse, BusinessHoursResource, type Calendar, type CalendarItemResponse, CalendarsResource, type Call, type CallAttempt, type CallItemResponse, CallsResource, type CampaignHopperResponse, type CampaignItemResponse, type CampaignRealtimeStatusResponse, type CampaignStatisticsResponse, CampaignsResource, type Conference, type ConferenceItemResponse, ConferencesResource, type Conversation, type ConversationEvent, type ConversationItemResponse, type ConversationSessionVariables, ConversationsResource, type CreateCampaignRequest, type CreateListRequest, type CreateManagedUserRequest, type CreateOutboundListRequest, type CreateTestCall, DEFAULT_BASE_URL, type Dashboard, type DashboardCreateBody, type DashboardItemResponse, type DashboardUpdateBody, type DashboardUser, type DashboardUsersResponse, DashboardsResource, type DefaultV2MessageResponse, type DialerBehaviour, type DialerBehaviourItemResponse, type DialerBehaviourWriteBody, DialerBehavioursResource, DialerResource, type DialerSimpleReportingQuery, EventsResource, ExpressionsResource, type FileBulkDeleteRequest, type FileBulkDownloadRequest, FilesResource, type GenericItemResponse, type GlobalAutomation, type GlobalAutomationItemResponse, type ImportAgentsOptions, type Integration, type IntegrationBulkIdsRequest, type IntegrationCreateRequest, type IntegrationItemResponse, type IntegrationObjectListResponse, type IntegrationProvider, type IntegrationTokenItemResponse, type IntegrationTokenListResponse, type IntegrationUpdateRequest, IntegrationsResource, type InterruptionTargetStates, type IvrModule, type Lead, type LeadBulkDeleteRequest, type LeadListItemResponse, type LeadUploadRequest, type LeadUploadResponse, type ListAgentsQuery, type ListApplicationsQuery, type ListAuditLogsQuery, type ListAutomationsQuery, type ListBabeldeskWidgetsQuery, type ListBabeldesksQuery, type ListBusinessHoursQuery, type ListCalendarsQuery, type ListConferencesQuery, type ListConversationsQuery, type ListDashboardsQuery, type ListDialerBehavioursQuery, type ListFilesQuery, type ListIntegrationsQuery, type ListNumbersQuery, type ListOutboundAttemptsQuery, type ListOutboundLeadsQuery, type ListPhonebookQuery, type ListProcessedOutboundLeadsQuery, type ListPromptsQuery, type ListQueuesQuery, type ListRecordingsQuery, type ListRoutingsQuery, type ListSmsQuery, type ListTasksQuery, type ListTriggersQuery, type ListUsersQuery, type LocalAutomation, type LocalAutomationItemResponse, LogsResource, type ManagedUser, type ManagedUserItemResponse, ManagerApiError, ManagerClient, type ManagerClientOptions, MeResource, type MetricDefinitionItemResponse, type MetricIdItemsResponse, type MetricResponse, MetricsResource, NumbersResource, type OAuthRevokeRequest, type OAuthTokenRequest, type OAuthTokenResponse, type ObjectListResponse, type OutboundCampaign, type OutboundCampaignItemResponse, type OutboundLeadItemResponse, type OutboundList, type OutboundListItemResponse, OutboundResource, type OutboundSimpleReportingQuery, type PaginatedAttemptResponse, type PaginatedLeadResponse, type PaginatedRecordingResponse, type PhonebookCsvFile, type PhonebookEntry, type PhonebookEntryItemResponse, PhonebookResource, type PkceChallenge, type Prompt, type PromptAudioFile, type PromptItemResponse, PromptsResource, type Queue, type QueueItemResponse, type QueueSelection, type QueueSelectionItemResponse, QueueSelectionsResource, type QueueTriggerListResponse, QueuesResource, type Recording, type RecordingItemResponse, type RecordingStartRequest, type RecordingState, type RecordingUpdateBody, RecordingsResource, type ReportingCall, type ReportingCallsQuery, ReportingResource, type RestCreateAgentBody, type RestCreateAgentGroupBody, type RestCreateBabeldeskBody, type RestCreateBabeldeskWidgetBody, type RestCreateBusinessHourBody, type RestCreateCalendarBody, type RestCreateConversationBody, type RestCreateGlobalAutomationBody, type RestCreateLocalAutomationBody, type RestCreatePhonebookEntryBody, type RestCreateQueueBody, type RestCreateQueueSelectionBody, type RestCreateRoutingBody, type RestCreateTriggerBody, type RestUpdateAgentBody, type RestUpdateAgentGroupBody, type RestUpdateBabeldeskBody, type RestUpdateBabeldeskWidgetBody, type RestUpdateBusinessHourBody, type RestUpdateCalendarBody, type RestUpdateConversationBody, type RestUpdateGlobalAutomationBody, type RestUpdateLocalAutomationBody, type RestUpdatePhonebookEntryBody, type RestUpdatePromptBody, type RestUpdateQueueBody, type RestUpdateQueueSelectionBody, type RestUpdateRoutingBody, type RestUpdateTriggerBody, type RetryOptions, type Routing, type RoutingItemResponse, RoutingResource, type ServiceNumber, type ServiceNumberItemResponse, type SessionResponse, SessionsResource, type SetCampaignListRequest, SettingAccessor, type SettingsAppAgentStatus, type SettingsAppConversations, type SettingsAppCustomerLogging, type SettingsAppIntegrations, type SettingsAuditDefault, SettingsResource, type SettingsRetentionPeriods, type SettingsTelephonyAgentInbound, type SettingsTelephonyAgentOutbound, type SettingsTelephonyAgentRecording, type SettingsTelephonyAgentWrapup, type SettingsTelephonyPostCall, type SettingsUiI18N, type SimpleReportingCallsQuery, type Sms, type SmsItemResponse, SmsResource, type StorageState, type StorageType, type StoredFile, type StoredFileItemResponse, type SubmitTaskBody, type SubmitTaskScheduleBody, SystemResource, type Tag, type Task, TaskMetricsResource, type TaskSchedule, TaskSchedulesResource, TaskScriptsResource, TaskSecretsResource, TaskSelectionConfigResource, type TaskTemplateOverrides, TasksResource, type TokenResponse, type Trigger, type TriggerConditionListResponse, type TriggerConditionsRequest, type TriggerItemResponse, type TriggerUsesResponse, TriggersResource, type UpdateAgentStatusRequest, type UpdateCampaignRequest, type UpdateSessionVariablesRequest, type UpdateTaskBody, type User, type UserCustomer, type UserCustomerItemResponse, type UserItemResponse, UsersResource, authorizationCodeGrant, buildAuthorizeUrl, clientCredentialsGrant, passwordGrant, pkceChallenge, refreshTokenGrant, withRetry };

package/dist/index.js

@@ -3,6 +3,29 @@ import { createClient, createConfig, urlSearchParamsBodySerializer, formDataBody
 // src/client.ts
 
 // src/auth.ts
+function base64url(bytes) {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function pkceChallenge() {
+  const codeVerifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(codeVerifier));
+  return { codeVerifier, codeChallenge: base64url(new Uint8Array(digest)), codeChallengeMethod: "S256" };
+}
+function buildAuthorizeUrl(opts) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: opts.clientId,
+    redirect_uri: opts.redirectUri,
+    scope: opts.scope,
+    code_challenge: opts.codeChallenge,
+    code_challenge_method: opts.codeChallengeMethod ?? "S256"
+  });
+  if (opts.state !== void 0) params.set("state", opts.state);
+  return `${base}/oauth/authorize?${params.toString()}`;
+}
 async function passwordGrant(opts) {
   const base = opts.baseUrl.replace(/\/+$/, "");
   const body = new URLSearchParams({
@@ -42,18 +65,71 @@ async function clientCredentialsGrant(opts) {
   }
   return json;
 }
+async function authorizationCodeGrant(opts) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: opts.code,
+    redirect_uri: opts.redirectUri,
+    client_id: opts.clientId,
+    code_verifier: opts.codeVerifier
+  });
+  if (opts.clientSecret !== void 0) body.set("client_secret", opts.clientSecret);
+  const doFetch = opts.fetch ?? fetch;
+  const resp = await doFetch(`${base}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body
+  });
+  const json = await resp.json().catch(() => ({}));
+  if (!resp.ok || !json.access_token) {
+    throw new Error(`authorization_code grant failed (status ${resp.status})`);
+  }
+  return json;
+}
+async function refreshTokenGrant(opts) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: opts.refreshToken
+  });
+  if (opts.clientId !== void 0) body.set("client_id", opts.clientId);
+  if (opts.clientSecret !== void 0) body.set("client_secret", opts.clientSecret);
+  const doFetch = opts.fetch ?? fetch;
+  const resp = await doFetch(`${base}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body
+  });
+  const json = await resp.json().catch(() => ({}));
+  if (!resp.ok || !json.access_token) {
+    throw new Error(`refresh_token grant failed (status ${resp.status})`);
+  }
+  return json;
+}
 var TokenManager = class {
-  constructor(grant) {
+  constructor(grant, initialRefresh) {
     this.grant = grant;
+    this.refreshToken = initialRefresh;
   }
   grant;
   token;
   expiresAt = 0;
+  refreshToken;
+  inflight;
   async get() {
     if (this.token && Date.now() < this.expiresAt - 3e4) return this.token;
-    const tok = await this.grant();
+    if (this.inflight) return this.inflight;
+    this.inflight = this.fetchToken().finally(() => {
+      this.inflight = void 0;
+    });
+    return this.inflight;
+  }
+  async fetchToken() {
+    const tok = await this.grant(this.refreshToken);
     this.token = tok.access_token;
     this.expiresAt = Date.now() + (tok.expires_in ? tok.expires_in * 1e3 : 36e5);
+    if (tok.refresh_token) this.refreshToken = tok.refresh_token;
     return this.token;
   }
 };
@@ -71,6 +147,19 @@ function buildAuthConfig(auth, baseUrl, fetchImpl) {
       );
       return { auth: (scheme) => scheme.scheme === "bearer" ? tokens.get() : void 0 };
     }
+    case "refreshToken": {
+      const tokens = new TokenManager(
+        (current) => refreshTokenGrant({
+          baseUrl,
+          refreshToken: current ?? auth.refreshToken,
+          clientId: auth.clientId,
+          clientSecret: auth.clientSecret,
+          fetch: fetchImpl
+        }),
+        auth.refreshToken
+      );
+      return { auth: (scheme) => scheme.scheme === "bearer" ? tokens.get() : void 0 };
+    }
   }
 }
 
@@ -8560,4 +8649,4 @@ var ManagerClient = class _ManagerClient {
   }
 };
 
-export { AgentGroupsResource, AgentsResource, AppActionsResource, ApplicationsResource, AuthResource, AutomationsResource, BabeldeskResource, BabeldeskWidgetsResource, BusinessHoursResource, CalendarsResource, CallsResource, CampaignsResource, ConferencesResource, ConversationsResource, DEFAULT_BASE_URL, DashboardsResource, DialerBehavioursResource, DialerResource, EventsResource, ExpressionsResource, FilesResource, IntegrationsResource, LogsResource, ManagerApiError, ManagerClient, MeResource, MetricsResource, NumbersResource, OutboundResource, PhonebookResource, PromptsResource, QueueSelectionsResource, QueuesResource, RecordingsResource, ReportingResource, RoutingResource, SessionsResource, SettingAccessor, SettingsResource, SmsResource, SystemResource, TaskMetricsResource, TaskSchedulesResource, TaskScriptsResource, TaskSecretsResource, TaskSelectionConfigResource, TasksResource, TriggersResource, UsersResource, passwordGrant, withRetry };
+export { AgentGroupsResource, AgentsResource, AppActionsResource, ApplicationsResource, AuthResource, AutomationsResource, BabeldeskResource, BabeldeskWidgetsResource, BusinessHoursResource, CalendarsResource, CallsResource, CampaignsResource, ConferencesResource, ConversationsResource, DEFAULT_BASE_URL, DashboardsResource, DialerBehavioursResource, DialerResource, EventsResource, ExpressionsResource, FilesResource, IntegrationsResource, LogsResource, ManagerApiError, ManagerClient, MeResource, MetricsResource, NumbersResource, OutboundResource, PhonebookResource, PromptsResource, QueueSelectionsResource, QueuesResource, RecordingsResource, ReportingResource, RoutingResource, SessionsResource, SettingAccessor, SettingsResource, SmsResource, SystemResource, TaskMetricsResource, TaskSchedulesResource, TaskScriptsResource, TaskSecretsResource, TaskSelectionConfigResource, TasksResource, TriggersResource, UsersResource, authorizationCodeGrant, buildAuthorizeUrl, clientCredentialsGrant, passwordGrant, pkceChallenge, refreshTokenGrant, withRetry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babelforce/manager-sdk",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "TypeScript SDK for the babelforce manager APIs — auth, user & agent management, call reporting, metrics, and task automations.",
   "license": "Apache-2.0",
   "type": "module",