@graph8/sdk 0.11.0 → 0.12.0

package/README.md

@@ -251,6 +251,57 @@ export const CTA = () => {
 | `g8.webhooks.constructEvent(body, sig, ts, secret, opts?)` | Verify a delivery's HMAC signature and return the parsed event (throws `WebhookSignatureError`) |
 | `g8.webhooks.knownEvents` | The known event-type catalog |
 
+## App Platform
+
+Hosted apps do not carry a permanent org API key. Instead they **exchange** a
+longer-lived credential for a short-lived graph8 app token, and the client
+mints, refreshes, and attaches it for you. Both clients expose a token-bound
+`request()` that reaches the existing Developer API resources with the app
+token.
+
+### Browser (PropelAuth token exchange)
+
+```typescript
+import { createGraph8AppClient } from '@graph8/sdk';
+
+// Exchange the signed-in user's PropelAuth token for a short-lived graph8 app
+// token. The client refreshes it on/near expiry and attaches
+// `Authorization: Bearer <app-token>` to every call — no API key in the browser.
+const appClient = createGraph8AppClient({
+  appId: 'dapp_your_app',
+  tenantOrgId: 'org_customer',
+  scopes: ['objects:read'],
+  getPropelAuthToken: () => localStorage.getItem('propelauth_token') ?? '',
+});
+
+// Reach the existing resources with the app token via request():
+const { data: contacts } = await appClient.request<{ data: unknown[] }>(
+  '/api/v1/contacts',
+  { query: { limit: 10 } },
+);
+```
+
+### Backend (service credentials)
+
+```typescript
+import { createGraph8ServiceClient } from '@graph8/sdk';
+
+// Exchange service client-credentials for a service token. Every call is pinned
+// to the one consented tenant via the `X-Target-Org-Id` header the client adds.
+const service = createGraph8ServiceClient({
+  clientId: process.env.G8_APP_CLIENT_ID,
+  clientSecret: process.env.G8_APP_CLIENT_SECRET,
+  tenantOrgId: 'org_customer',
+  scopes: ['objects:read', 'objects:write'],
+});
+
+const { data: rows } = await service.request<{ data: unknown[] }>('/api/v1/contacts');
+```
+
+> The typed `apps` (control-plane) and `objects` (custom-object CRUD) resource
+> modules are deferred until their backend routes ship (M6-3 / M6-5). Until then,
+> reach the Developer API through the token-bound `request()` shown above.
+
 ## Auth Modes
 
 | Mode | Key | Use case |

package/dist/index.d.mts

@@ -4016,4 +4016,229 @@ interface PaginatedResponse<T> {
  */
 declare function paginate<T>(fetchPage: (cursor?: string) => Promise<PaginatedResponse<T>>): AsyncGenerator<T, void, unknown>;
 
-export { type AddToSequenceConfig, type AgencyClient, type AgencyInfo, type AudienceSync, type AudienceSyncCreateParams, type AudienceSyncError, type AudienceSyncMode, type AudienceSyncPlatform, type AudienceSyncRun, type AudienceSyncUpdateParams, type Booking, type BookingRequest, type CalendarConfig, type CallGradingResult, type Campaign, type CampaignCreateConfig, type CampaignLaunchExecution, type CampaignLaunchResult, type ChatConfig, type Company, type CompanyColumn, type CompanyColumnCreateParams, type CompanyContact, type CompanyEnrichment, type CompanyListParams, type CompanyUpdateParams, type ConstructEventOptions, type Contact, type ContactColumn, type ContactColumnCreateParams, type ContactCreateParams, type ContactDeal, type ContactList, type ContactListParams, type ContactUpdateParams, type CopilotConfig, type CreatedField, type Deal, type DealCreateParams, type DealListParams, type DealUpdateParams, type DialerAgentSummary, type DialerAgentsListParams, type DialerAgentsListResult, type DialerNumberInfo, type DialerNumbersListResult, type DialerReportFilters, type DialerReportMetric, type DialerSessionCreateParams, type DialerSessionCreateResult, type DialerSessionResumeResult, type DialerSessionStatus, type DialerSessionStatusUpdateResult, type DialerSessionSummary, type DialerSessionsListParams, type DialerSessionsListResult, type DialerStatsParams, type DialerStatsResult, type EmailVerification, type EnrichLookupResult, type EvidenceKey, type Field, type FieldCreateParams, type FieldDeleteParams, type G8Config, G8Error, type G8PrivacyConfig, type GlobalContextDocument, type ICP, type IdentifyProperties, type InboxAssignResult, type InboxAssignee, type InboxChannel, type InboxContact, type InboxDraft, type InboxListParams, type InboxMessage, type InboxSendParams, type InboxSendResult, type InboxTag, type InboxTagResult, type InboxThread, type IntelligenceData, type IntentCompany, type IntentContact, type IntentKeyword, type IntentPage, type IntentSignals, type IntentStats, type IntentVisitor, KNOWN_WEBHOOK_EVENTS, type ListContact, type MarketplaceHiring, type MarketplaceOffer, type MarketplaceProfile, type MeetingAnalysis, type MeetingAttendee, type MeetingDetail, type MeetingListParams, type MeetingSummary, type MeetingTranscriptLine, type MissedCallback, type MissedCallbacksResult, type NodeTypeSchema, type Note, type PaginatedResponse, type PaginationMeta$1 as PaginationMeta, type PersonEnrichment, type Persona, type Pipeline, type PipelineStage, type PipelineSuggestion, type QuotableProduct, type QuoteCreateParams, type QuoteDetail, type QuoteLineItem, type QuoteListParams, type QuoteSendParams, type QuoteSettings, type QuoteStatus, type QuoteSummary, type QuoteUpdateParams, type RequestOptions, type ResearchReport, type SearchCompanyItem, type SearchCondition, type SearchContactItem, type SearchFilter, type SearchOperator, type SearchParams, type SearchResults, type SearchSaveParams, type SearchSaveResult, type Sequence, type SequenceActionResult, type SequenceAnalytics, type SequenceChannelConfig, type SequenceContactItem, type SequenceContactsParams, type SequenceCreateParams, type SequenceCreateResult, type SequenceDetail, type SequenceKind, type SequenceListItem, type SequenceListParams, type SequencePreview, type SequencePreviewChannel, type SequencePreviewStep, type SequenceStepConfig, type SequenceStepInputType, type SequenceStepType, type SequenceStepUpdateParams, type SequenceUpdateParams, type SetFieldValueParams, type Skill, type SkillCreateAPIParams, type SkillCreateLLMParams, type SkillInputField, type SkillListParams, type SkillTemplate, type SkillType, type SkillUpdateAPIParams, type SkillUpdateLLMParams, type Snippet, type StageCreateParams, type StagePipeline, type StagePipelineCreateParams, type StagePipelineStage, type StagePipelineUpdateParams, type StageUpdateParams, type Task, type TaskCreateParams, type TaskListParams, type TaskUpdateParams, type TimeSlot, type TrackProperties, type VisitorCompany, type VisitorScore, type VoicePagination, type WebhookEvent, type WebhookEventPayload, WebhookSignatureError, type Workflow, type WorkflowConfig, type WorkflowConnection, type WorkflowCreateParams, type WorkflowExecution, type WorkflowListParams, type WorkflowNode, type WorkflowUpdateParams, backoffDelayMs, constructEvent, g8, isRetryableStatus, paginate, parseRetryAfter, request };
+/**
+ * App-platform token exchange + refresh core (M6-9).
+ *
+ * The hosted-app clients never carry a permanent org API key. Instead they mint
+ * SHORT-LIVED app tokens by EXCHANGING a longer-lived credential, and refresh
+ * them on/near expiry:
+ *
+ *   - browser apps exchange the caller's PropelAuth login at
+ *     `POST /api/v1/app-sessions/exchange` (identity is derived server-side from
+ *     the validated principal — the body only names the target app + scopes);
+ *   - hosted backends exchange service client-credentials at
+ *     `POST /api/v1/service-token`.
+ *
+ * Both endpoints answer with the reused `ApiResponse` envelope wrapping a
+ * `TokenResponse` (see developer_api/app_platform/app_tokens/dtos.py). This
+ * module owns:
+ *
+ *   - `AppTokenResponse` — the minted-token payload shape (frozen wire contract);
+ *   - `createTokenManager` — caches a token, refreshes it on/near expiry, and
+ *     de-dupes concurrent refreshes into one in-flight exchange;
+ *   - `createAppRequester` — binds the managed token onto the hardened
+ *     `request()` core (typed `G8Error`, retries, idempotency, pagination),
+ *     attaching `Authorization: Bearer <app-token>` (plus any static header such
+ *     as a service client's `X-Target-Org-Id`) and refreshing once on a 401.
+ *
+ * The backend app-token API is INERT/unmounted today (behind a deny-by-default
+ * flag), so these paths are exercised against mocked HTTP, never a live server.
+ */
+declare const DEFAULT_APP_API = "https://be.graph8.com";
+/** The minted app token + the non-secret metadata a client reads back.
+ *  Mirrors `TokenResponse` in developer_api/app_platform/app_tokens/dtos.py. */
+interface AppTokenResponse {
+    /** The signed app JWT (attach as `Authorization: Bearer <access_token>`). */
+    access_token: string;
+    /** Always "Bearer". */
+    token_type: string;
+    /** Lifetime in seconds from issuance. */
+    expires_in: number;
+    /** The distinct-per-app, per-environment audience. */
+    audience: string;
+    /** App the token is bound to (dapp_-prefixed). */
+    app_id: string;
+    /** Signing key id (matches a JWKS entry). */
+    kid: string;
+}
+/** Per-request options accepted by an {@link AppRequest}. A subset of the
+ *  hardened core's `RequestOptions` — auth (the app token) and the injected
+ *  fetch/sleep seams are bound by the requester, not passed per call. */
+interface AppRequestOptions {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    /** Sent as `Idempotency-Key` for safe POST/PATCH retries. */
+    idempotencyKey?: string;
+    /** Max retry attempts on 429/5xx/network (default 2). */
+    maxRetries?: number;
+    /** Base backoff in ms (default 200). */
+    retryBaseMs?: number;
+    signal?: AbortSignal;
+}
+/** A token-bound request function: same ergonomics as the raw `request()` core
+ *  minus the credential, which the token manager supplies. */
+type AppRequest = <T = unknown>(path: string, opts?: AppRequestOptions) => Promise<T>;
+/** Caches + refreshes one app token. */
+interface TokenManager {
+    /** Return a valid token, refreshing on/near expiry. `force` refreshes now. */
+    getToken(force?: boolean): Promise<string>;
+    /** Current token expiry as an epoch-ms timestamp (0 before the first mint). */
+    expiresAt(): number;
+}
+/**
+ * Build a token manager over a `refresh` exchange.
+ *
+ * Freshness rule: a cached token is reused until it is within `refreshSkewMs`
+ * of expiry, then a refresh is triggered. Concurrent callers during a refresh
+ * share ONE in-flight exchange (no stampede). `now` is injectable for tests.
+ */
+declare function createTokenManager(args: {
+    refresh: () => Promise<AppTokenResponse>;
+    now?: () => number;
+    refreshSkewMs?: number;
+}): TokenManager;
+/**
+ * Bind a {@link TokenManager} onto the hardened `request()` core.
+ *
+ * Every call fetches the current token, attaches `Authorization: Bearer …`
+ * (plus any `extraHeaders`, e.g. a service client's `X-Target-Org-Id`), and
+ * reuses all of the core's typed errors / retries / idempotency. On a 401 —
+ * a token revoked or gone stale mid-window — it force-refreshes ONCE and retries.
+ */
+declare function createAppRequester(args: {
+    baseUrl: string;
+    tokens: TokenManager;
+    extraHeaders?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): AppRequest;
+/**
+ * Exchange the caller's PropelAuth token for a short-lived BROWSER app token.
+ * `POST /api/v1/app-sessions/exchange` (body = target app + scopes only;
+ * identity/role/tenant are derived server-side from the validated principal).
+ */
+declare function exchangeBrowserToken(args: {
+    baseUrl: string;
+    appId: string;
+    scopes?: string[];
+    getPropelAuthToken: () => string | Promise<string>;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): Promise<AppTokenResponse>;
+/**
+ * Exchange service client-credentials for a SERVICE app token.
+ * `POST /api/v1/service-token` — credentials travel in the body; this endpoint
+ * has no bearer auth, so no `Authorization` is sent on the exchange itself.
+ */
+declare function exchangeServiceToken(args: {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+    ttlSeconds?: number;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): Promise<AppTokenResponse>;
+
+/**
+ * Hosted app-platform clients (M6-9).
+ *
+ * Two entry points, both additive to `@graph8/sdk` and independent of the
+ * `g8` tracking/API-key singleton:
+ *
+ *   - `createGraph8AppClient` — BROWSER client. Exchanges the caller's
+ *     PropelAuth token for a short-lived app token, refreshes it on/near expiry,
+ *     and attaches `Authorization: Bearer <app-token>` to every call. It NEVER
+ *     accepts a permanent org API key for browser init (the whole reason the
+ *     token-exchange exists).
+ *   - `createGraph8ServiceClient` — BACKEND client. Exchanges service
+ *     client-credentials for a service app token and sends `X-Target-Org-Id`
+ *     for the single configured tenant on every call.
+ *
+ * Both expose a token-bound `request()` — the hardened `request()` core with the
+ * minted app token attached — so callers reach Developer API routes with the
+ * app token and reuse the core's typed `G8Error`, retries, idempotency, and
+ * cursor pagination. The typed `apps` (control-plane) and `objects`
+ * (custom-object CRUD) resource modules are DEFERRED until their backend routes
+ * ship and freeze (M6-3 / M6-5); only the auth clients ship here.
+ */
+
+/** Config for {@link createGraph8AppClient} (browser). No API key is accepted. */
+interface Graph8AppClientConfig {
+    /** Target app id (dapp_-prefixed). */
+    appId: string;
+    /** The client org this browser session acts in (informational; the server
+     *  derives the authoritative tenant from the validated PropelAuth principal). */
+    tenantOrgId: string;
+    /** Returns the caller's current PropelAuth token (sync or async). */
+    getPropelAuthToken: () => string | Promise<string>;
+    /** Scopes to embed in the minted app token. */
+    scopes?: string[];
+    /** Backend API URL (default https://be.graph8.com). */
+    apiUrl?: string;
+    /** Refresh this many ms before expiry (default 60_000). */
+    refreshSkewMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests; defaults to a real setTimeout sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injected for tests; defaults to Date.now. */
+    now?: () => number;
+}
+/** A browser app-platform client. */
+interface Graph8AppClient {
+    readonly appId: string;
+    readonly tenantOrgId: string;
+    /** Token-bound requester: mints/refreshes the app token and attaches
+     *  `Authorization: Bearer <app-token>` to every Developer API call. */
+    readonly request: AppRequest;
+    /** Return the current app token, refreshing on/near expiry (`force` refreshes now). */
+    getAppToken(force?: boolean): Promise<string>;
+}
+/**
+ * Create a BROWSER app-platform client backed by PropelAuth->app-token exchange.
+ * Refuses an org API key / write key — those must never reach a browser.
+ */
+declare function createGraph8AppClient(config: Graph8AppClientConfig): Graph8AppClient;
+/** Config for {@link createGraph8ServiceClient} (backend / server-to-server). */
+interface Graph8ServiceClientConfig {
+    /** Service credential client id. */
+    clientId: string;
+    /** Service credential client secret (checked against the stored hash). */
+    clientSecret: string;
+    /** The single consented client org this backend acts for (sent as X-Target-Org-Id). */
+    tenantOrgId: string;
+    /** Scopes to embed in the minted service token. */
+    scopes?: string[];
+    /** Requested token TTL; the server clamps it into its service band. */
+    ttlSeconds?: number;
+    /** Backend API URL (default https://be.graph8.com). */
+    apiUrl?: string;
+    /** Refresh this many ms before expiry (default 60_000). */
+    refreshSkewMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests; defaults to a real setTimeout sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injected for tests; defaults to Date.now. */
+    now?: () => number;
+}
+/** A backend service app-platform client. */
+interface Graph8ServiceClient {
+    readonly tenantOrgId: string;
+    /** Token-bound requester: mints/refreshes the service token, attaches it, and
+     *  sends `X-Target-Org-Id` for the one consented tenant on every call. */
+    readonly request: AppRequest;
+    /** Return the current service token, refreshing on/near expiry (`force` refreshes now). */
+    getServiceToken(force?: boolean): Promise<string>;
+}
+/**
+ * Create a BACKEND service client backed by client-credentials->service-token
+ * exchange. Every request carries `X-Target-Org-Id: <tenantOrgId>` for the one
+ * configured consented tenant.
+ */
+declare function createGraph8ServiceClient(config: Graph8ServiceClientConfig): Graph8ServiceClient;
+
+export { type AddToSequenceConfig, type AgencyClient, type AgencyInfo, type AppRequest, type AppRequestOptions, type AppTokenResponse, type AudienceSync, type AudienceSyncCreateParams, type AudienceSyncError, type AudienceSyncMode, type AudienceSyncPlatform, type AudienceSyncRun, type AudienceSyncUpdateParams, type Booking, type BookingRequest, type CalendarConfig, type CallGradingResult, type Campaign, type CampaignCreateConfig, type CampaignLaunchExecution, type CampaignLaunchResult, type ChatConfig, type Company, type CompanyColumn, type CompanyColumnCreateParams, type CompanyContact, type CompanyEnrichment, type CompanyListParams, type CompanyUpdateParams, type ConstructEventOptions, type Contact, type ContactColumn, type ContactColumnCreateParams, type ContactCreateParams, type ContactDeal, type ContactList, type ContactListParams, type ContactUpdateParams, type CopilotConfig, type CreatedField, DEFAULT_APP_API, type Deal, type DealCreateParams, type DealListParams, type DealUpdateParams, type DialerAgentSummary, type DialerAgentsListParams, type DialerAgentsListResult, type DialerNumberInfo, type DialerNumbersListResult, type DialerReportFilters, type DialerReportMetric, type DialerSessionCreateParams, type DialerSessionCreateResult, type DialerSessionResumeResult, type DialerSessionStatus, type DialerSessionStatusUpdateResult, type DialerSessionSummary, type DialerSessionsListParams, type DialerSessionsListResult, type DialerStatsParams, type DialerStatsResult, type EmailVerification, type EnrichLookupResult, type EvidenceKey, type Field, type FieldCreateParams, type FieldDeleteParams, type G8Config, G8Error, type G8PrivacyConfig, type GlobalContextDocument, type Graph8AppClient, type Graph8AppClientConfig, type Graph8ServiceClient, type Graph8ServiceClientConfig, type ICP, type IdentifyProperties, type InboxAssignResult, type InboxAssignee, type InboxChannel, type InboxContact, type InboxDraft, type InboxListParams, type InboxMessage, type InboxSendParams, type InboxSendResult, type InboxTag, type InboxTagResult, type InboxThread, type IntelligenceData, type IntentCompany, type IntentContact, type IntentKeyword, type IntentPage, type IntentSignals, type IntentStats, type IntentVisitor, KNOWN_WEBHOOK_EVENTS, type ListContact, type MarketplaceHiring, type MarketplaceOffer, type MarketplaceProfile, type MeetingAnalysis, type MeetingAttendee, type MeetingDetail, type MeetingListParams, type MeetingSummary, type MeetingTranscriptLine, type MissedCallback, type MissedCallbacksResult, type NodeTypeSchema, type Note, type PaginatedResponse, type PaginationMeta$1 as PaginationMeta, type PersonEnrichment, type Persona, type Pipeline, type PipelineStage, type PipelineSuggestion, type QuotableProduct, type QuoteCreateParams, type QuoteDetail, type QuoteLineItem, type QuoteListParams, type QuoteSendParams, type QuoteSettings, type QuoteStatus, type QuoteSummary, type QuoteUpdateParams, type RequestOptions, type ResearchReport, type SearchCompanyItem, type SearchCondition, type SearchContactItem, type SearchFilter, type SearchOperator, type SearchParams, type SearchResults, type SearchSaveParams, type SearchSaveResult, type Sequence, type SequenceActionResult, type SequenceAnalytics, type SequenceChannelConfig, type SequenceContactItem, type SequenceContactsParams, type SequenceCreateParams, type SequenceCreateResult, type SequenceDetail, type SequenceKind, type SequenceListItem, type SequenceListParams, type SequencePreview, type SequencePreviewChannel, type SequencePreviewStep, type SequenceStepConfig, type SequenceStepInputType, type SequenceStepType, type SequenceStepUpdateParams, type SequenceUpdateParams, type SetFieldValueParams, type Skill, type SkillCreateAPIParams, type SkillCreateLLMParams, type SkillInputField, type SkillListParams, type SkillTemplate, type SkillType, type SkillUpdateAPIParams, type SkillUpdateLLMParams, type Snippet, type StageCreateParams, type StagePipeline, type StagePipelineCreateParams, type StagePipelineStage, type StagePipelineUpdateParams, type StageUpdateParams, type Task, type TaskCreateParams, type TaskListParams, type TaskUpdateParams, type TimeSlot, type TokenManager, type TrackProperties, type VisitorCompany, type VisitorScore, type VoicePagination, type WebhookEvent, type WebhookEventPayload, WebhookSignatureError, type Workflow, type WorkflowConfig, type WorkflowConnection, type WorkflowCreateParams, type WorkflowExecution, type WorkflowListParams, type WorkflowNode, type WorkflowUpdateParams, backoffDelayMs, constructEvent, createAppRequester, createGraph8AppClient, createGraph8ServiceClient, createTokenManager, exchangeBrowserToken, exchangeServiceToken, g8, isRetryableStatus, paginate, parseRetryAfter, request };

package/dist/index.d.ts

@@ -4016,4 +4016,229 @@ interface PaginatedResponse<T> {
  */
 declare function paginate<T>(fetchPage: (cursor?: string) => Promise<PaginatedResponse<T>>): AsyncGenerator<T, void, unknown>;
 
-export { type AddToSequenceConfig, type AgencyClient, type AgencyInfo, type AudienceSync, type AudienceSyncCreateParams, type AudienceSyncError, type AudienceSyncMode, type AudienceSyncPlatform, type AudienceSyncRun, type AudienceSyncUpdateParams, type Booking, type BookingRequest, type CalendarConfig, type CallGradingResult, type Campaign, type CampaignCreateConfig, type CampaignLaunchExecution, type CampaignLaunchResult, type ChatConfig, type Company, type CompanyColumn, type CompanyColumnCreateParams, type CompanyContact, type CompanyEnrichment, type CompanyListParams, type CompanyUpdateParams, type ConstructEventOptions, type Contact, type ContactColumn, type ContactColumnCreateParams, type ContactCreateParams, type ContactDeal, type ContactList, type ContactListParams, type ContactUpdateParams, type CopilotConfig, type CreatedField, type Deal, type DealCreateParams, type DealListParams, type DealUpdateParams, type DialerAgentSummary, type DialerAgentsListParams, type DialerAgentsListResult, type DialerNumberInfo, type DialerNumbersListResult, type DialerReportFilters, type DialerReportMetric, type DialerSessionCreateParams, type DialerSessionCreateResult, type DialerSessionResumeResult, type DialerSessionStatus, type DialerSessionStatusUpdateResult, type DialerSessionSummary, type DialerSessionsListParams, type DialerSessionsListResult, type DialerStatsParams, type DialerStatsResult, type EmailVerification, type EnrichLookupResult, type EvidenceKey, type Field, type FieldCreateParams, type FieldDeleteParams, type G8Config, G8Error, type G8PrivacyConfig, type GlobalContextDocument, type ICP, type IdentifyProperties, type InboxAssignResult, type InboxAssignee, type InboxChannel, type InboxContact, type InboxDraft, type InboxListParams, type InboxMessage, type InboxSendParams, type InboxSendResult, type InboxTag, type InboxTagResult, type InboxThread, type IntelligenceData, type IntentCompany, type IntentContact, type IntentKeyword, type IntentPage, type IntentSignals, type IntentStats, type IntentVisitor, KNOWN_WEBHOOK_EVENTS, type ListContact, type MarketplaceHiring, type MarketplaceOffer, type MarketplaceProfile, type MeetingAnalysis, type MeetingAttendee, type MeetingDetail, type MeetingListParams, type MeetingSummary, type MeetingTranscriptLine, type MissedCallback, type MissedCallbacksResult, type NodeTypeSchema, type Note, type PaginatedResponse, type PaginationMeta$1 as PaginationMeta, type PersonEnrichment, type Persona, type Pipeline, type PipelineStage, type PipelineSuggestion, type QuotableProduct, type QuoteCreateParams, type QuoteDetail, type QuoteLineItem, type QuoteListParams, type QuoteSendParams, type QuoteSettings, type QuoteStatus, type QuoteSummary, type QuoteUpdateParams, type RequestOptions, type ResearchReport, type SearchCompanyItem, type SearchCondition, type SearchContactItem, type SearchFilter, type SearchOperator, type SearchParams, type SearchResults, type SearchSaveParams, type SearchSaveResult, type Sequence, type SequenceActionResult, type SequenceAnalytics, type SequenceChannelConfig, type SequenceContactItem, type SequenceContactsParams, type SequenceCreateParams, type SequenceCreateResult, type SequenceDetail, type SequenceKind, type SequenceListItem, type SequenceListParams, type SequencePreview, type SequencePreviewChannel, type SequencePreviewStep, type SequenceStepConfig, type SequenceStepInputType, type SequenceStepType, type SequenceStepUpdateParams, type SequenceUpdateParams, type SetFieldValueParams, type Skill, type SkillCreateAPIParams, type SkillCreateLLMParams, type SkillInputField, type SkillListParams, type SkillTemplate, type SkillType, type SkillUpdateAPIParams, type SkillUpdateLLMParams, type Snippet, type StageCreateParams, type StagePipeline, type StagePipelineCreateParams, type StagePipelineStage, type StagePipelineUpdateParams, type StageUpdateParams, type Task, type TaskCreateParams, type TaskListParams, type TaskUpdateParams, type TimeSlot, type TrackProperties, type VisitorCompany, type VisitorScore, type VoicePagination, type WebhookEvent, type WebhookEventPayload, WebhookSignatureError, type Workflow, type WorkflowConfig, type WorkflowConnection, type WorkflowCreateParams, type WorkflowExecution, type WorkflowListParams, type WorkflowNode, type WorkflowUpdateParams, backoffDelayMs, constructEvent, g8, isRetryableStatus, paginate, parseRetryAfter, request };
+/**
+ * App-platform token exchange + refresh core (M6-9).
+ *
+ * The hosted-app clients never carry a permanent org API key. Instead they mint
+ * SHORT-LIVED app tokens by EXCHANGING a longer-lived credential, and refresh
+ * them on/near expiry:
+ *
+ *   - browser apps exchange the caller's PropelAuth login at
+ *     `POST /api/v1/app-sessions/exchange` (identity is derived server-side from
+ *     the validated principal — the body only names the target app + scopes);
+ *   - hosted backends exchange service client-credentials at
+ *     `POST /api/v1/service-token`.
+ *
+ * Both endpoints answer with the reused `ApiResponse` envelope wrapping a
+ * `TokenResponse` (see developer_api/app_platform/app_tokens/dtos.py). This
+ * module owns:
+ *
+ *   - `AppTokenResponse` — the minted-token payload shape (frozen wire contract);
+ *   - `createTokenManager` — caches a token, refreshes it on/near expiry, and
+ *     de-dupes concurrent refreshes into one in-flight exchange;
+ *   - `createAppRequester` — binds the managed token onto the hardened
+ *     `request()` core (typed `G8Error`, retries, idempotency, pagination),
+ *     attaching `Authorization: Bearer <app-token>` (plus any static header such
+ *     as a service client's `X-Target-Org-Id`) and refreshing once on a 401.
+ *
+ * The backend app-token API is INERT/unmounted today (behind a deny-by-default
+ * flag), so these paths are exercised against mocked HTTP, never a live server.
+ */
+declare const DEFAULT_APP_API = "https://be.graph8.com";
+/** The minted app token + the non-secret metadata a client reads back.
+ *  Mirrors `TokenResponse` in developer_api/app_platform/app_tokens/dtos.py. */
+interface AppTokenResponse {
+    /** The signed app JWT (attach as `Authorization: Bearer <access_token>`). */
+    access_token: string;
+    /** Always "Bearer". */
+    token_type: string;
+    /** Lifetime in seconds from issuance. */
+    expires_in: number;
+    /** The distinct-per-app, per-environment audience. */
+    audience: string;
+    /** App the token is bound to (dapp_-prefixed). */
+    app_id: string;
+    /** Signing key id (matches a JWKS entry). */
+    kid: string;
+}
+/** Per-request options accepted by an {@link AppRequest}. A subset of the
+ *  hardened core's `RequestOptions` — auth (the app token) and the injected
+ *  fetch/sleep seams are bound by the requester, not passed per call. */
+interface AppRequestOptions {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    /** Sent as `Idempotency-Key` for safe POST/PATCH retries. */
+    idempotencyKey?: string;
+    /** Max retry attempts on 429/5xx/network (default 2). */
+    maxRetries?: number;
+    /** Base backoff in ms (default 200). */
+    retryBaseMs?: number;
+    signal?: AbortSignal;
+}
+/** A token-bound request function: same ergonomics as the raw `request()` core
+ *  minus the credential, which the token manager supplies. */
+type AppRequest = <T = unknown>(path: string, opts?: AppRequestOptions) => Promise<T>;
+/** Caches + refreshes one app token. */
+interface TokenManager {
+    /** Return a valid token, refreshing on/near expiry. `force` refreshes now. */
+    getToken(force?: boolean): Promise<string>;
+    /** Current token expiry as an epoch-ms timestamp (0 before the first mint). */
+    expiresAt(): number;
+}
+/**
+ * Build a token manager over a `refresh` exchange.
+ *
+ * Freshness rule: a cached token is reused until it is within `refreshSkewMs`
+ * of expiry, then a refresh is triggered. Concurrent callers during a refresh
+ * share ONE in-flight exchange (no stampede). `now` is injectable for tests.
+ */
+declare function createTokenManager(args: {
+    refresh: () => Promise<AppTokenResponse>;
+    now?: () => number;
+    refreshSkewMs?: number;
+}): TokenManager;
+/**
+ * Bind a {@link TokenManager} onto the hardened `request()` core.
+ *
+ * Every call fetches the current token, attaches `Authorization: Bearer …`
+ * (plus any `extraHeaders`, e.g. a service client's `X-Target-Org-Id`), and
+ * reuses all of the core's typed errors / retries / idempotency. On a 401 —
+ * a token revoked or gone stale mid-window — it force-refreshes ONCE and retries.
+ */
+declare function createAppRequester(args: {
+    baseUrl: string;
+    tokens: TokenManager;
+    extraHeaders?: Record<string, string>;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): AppRequest;
+/**
+ * Exchange the caller's PropelAuth token for a short-lived BROWSER app token.
+ * `POST /api/v1/app-sessions/exchange` (body = target app + scopes only;
+ * identity/role/tenant are derived server-side from the validated principal).
+ */
+declare function exchangeBrowserToken(args: {
+    baseUrl: string;
+    appId: string;
+    scopes?: string[];
+    getPropelAuthToken: () => string | Promise<string>;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): Promise<AppTokenResponse>;
+/**
+ * Exchange service client-credentials for a SERVICE app token.
+ * `POST /api/v1/service-token` — credentials travel in the body; this endpoint
+ * has no bearer auth, so no `Authorization` is sent on the exchange itself.
+ */
+declare function exchangeServiceToken(args: {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+    ttlSeconds?: number;
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}): Promise<AppTokenResponse>;
+
+/**
+ * Hosted app-platform clients (M6-9).
+ *
+ * Two entry points, both additive to `@graph8/sdk` and independent of the
+ * `g8` tracking/API-key singleton:
+ *
+ *   - `createGraph8AppClient` — BROWSER client. Exchanges the caller's
+ *     PropelAuth token for a short-lived app token, refreshes it on/near expiry,
+ *     and attaches `Authorization: Bearer <app-token>` to every call. It NEVER
+ *     accepts a permanent org API key for browser init (the whole reason the
+ *     token-exchange exists).
+ *   - `createGraph8ServiceClient` — BACKEND client. Exchanges service
+ *     client-credentials for a service app token and sends `X-Target-Org-Id`
+ *     for the single configured tenant on every call.
+ *
+ * Both expose a token-bound `request()` — the hardened `request()` core with the
+ * minted app token attached — so callers reach Developer API routes with the
+ * app token and reuse the core's typed `G8Error`, retries, idempotency, and
+ * cursor pagination. The typed `apps` (control-plane) and `objects`
+ * (custom-object CRUD) resource modules are DEFERRED until their backend routes
+ * ship and freeze (M6-3 / M6-5); only the auth clients ship here.
+ */
+
+/** Config for {@link createGraph8AppClient} (browser). No API key is accepted. */
+interface Graph8AppClientConfig {
+    /** Target app id (dapp_-prefixed). */
+    appId: string;
+    /** The client org this browser session acts in (informational; the server
+     *  derives the authoritative tenant from the validated PropelAuth principal). */
+    tenantOrgId: string;
+    /** Returns the caller's current PropelAuth token (sync or async). */
+    getPropelAuthToken: () => string | Promise<string>;
+    /** Scopes to embed in the minted app token. */
+    scopes?: string[];
+    /** Backend API URL (default https://be.graph8.com). */
+    apiUrl?: string;
+    /** Refresh this many ms before expiry (default 60_000). */
+    refreshSkewMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests; defaults to a real setTimeout sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injected for tests; defaults to Date.now. */
+    now?: () => number;
+}
+/** A browser app-platform client. */
+interface Graph8AppClient {
+    readonly appId: string;
+    readonly tenantOrgId: string;
+    /** Token-bound requester: mints/refreshes the app token and attaches
+     *  `Authorization: Bearer <app-token>` to every Developer API call. */
+    readonly request: AppRequest;
+    /** Return the current app token, refreshing on/near expiry (`force` refreshes now). */
+    getAppToken(force?: boolean): Promise<string>;
+}
+/**
+ * Create a BROWSER app-platform client backed by PropelAuth->app-token exchange.
+ * Refuses an org API key / write key — those must never reach a browser.
+ */
+declare function createGraph8AppClient(config: Graph8AppClientConfig): Graph8AppClient;
+/** Config for {@link createGraph8ServiceClient} (backend / server-to-server). */
+interface Graph8ServiceClientConfig {
+    /** Service credential client id. */
+    clientId: string;
+    /** Service credential client secret (checked against the stored hash). */
+    clientSecret: string;
+    /** The single consented client org this backend acts for (sent as X-Target-Org-Id). */
+    tenantOrgId: string;
+    /** Scopes to embed in the minted service token. */
+    scopes?: string[];
+    /** Requested token TTL; the server clamps it into its service band. */
+    ttlSeconds?: number;
+    /** Backend API URL (default https://be.graph8.com). */
+    apiUrl?: string;
+    /** Refresh this many ms before expiry (default 60_000). */
+    refreshSkewMs?: number;
+    /** Injected for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Injected for tests; defaults to a real setTimeout sleep. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Injected for tests; defaults to Date.now. */
+    now?: () => number;
+}
+/** A backend service app-platform client. */
+interface Graph8ServiceClient {
+    readonly tenantOrgId: string;
+    /** Token-bound requester: mints/refreshes the service token, attaches it, and
+     *  sends `X-Target-Org-Id` for the one consented tenant on every call. */
+    readonly request: AppRequest;
+    /** Return the current service token, refreshing on/near expiry (`force` refreshes now). */
+    getServiceToken(force?: boolean): Promise<string>;
+}
+/**
+ * Create a BACKEND service client backed by client-credentials->service-token
+ * exchange. Every request carries `X-Target-Org-Id: <tenantOrgId>` for the one
+ * configured consented tenant.
+ */
+declare function createGraph8ServiceClient(config: Graph8ServiceClientConfig): Graph8ServiceClient;
+
+export { type AddToSequenceConfig, type AgencyClient, type AgencyInfo, type AppRequest, type AppRequestOptions, type AppTokenResponse, type AudienceSync, type AudienceSyncCreateParams, type AudienceSyncError, type AudienceSyncMode, type AudienceSyncPlatform, type AudienceSyncRun, type AudienceSyncUpdateParams, type Booking, type BookingRequest, type CalendarConfig, type CallGradingResult, type Campaign, type CampaignCreateConfig, type CampaignLaunchExecution, type CampaignLaunchResult, type ChatConfig, type Company, type CompanyColumn, type CompanyColumnCreateParams, type CompanyContact, type CompanyEnrichment, type CompanyListParams, type CompanyUpdateParams, type ConstructEventOptions, type Contact, type ContactColumn, type ContactColumnCreateParams, type ContactCreateParams, type ContactDeal, type ContactList, type ContactListParams, type ContactUpdateParams, type CopilotConfig, type CreatedField, DEFAULT_APP_API, type Deal, type DealCreateParams, type DealListParams, type DealUpdateParams, type DialerAgentSummary, type DialerAgentsListParams, type DialerAgentsListResult, type DialerNumberInfo, type DialerNumbersListResult, type DialerReportFilters, type DialerReportMetric, type DialerSessionCreateParams, type DialerSessionCreateResult, type DialerSessionResumeResult, type DialerSessionStatus, type DialerSessionStatusUpdateResult, type DialerSessionSummary, type DialerSessionsListParams, type DialerSessionsListResult, type DialerStatsParams, type DialerStatsResult, type EmailVerification, type EnrichLookupResult, type EvidenceKey, type Field, type FieldCreateParams, type FieldDeleteParams, type G8Config, G8Error, type G8PrivacyConfig, type GlobalContextDocument, type Graph8AppClient, type Graph8AppClientConfig, type Graph8ServiceClient, type Graph8ServiceClientConfig, type ICP, type IdentifyProperties, type InboxAssignResult, type InboxAssignee, type InboxChannel, type InboxContact, type InboxDraft, type InboxListParams, type InboxMessage, type InboxSendParams, type InboxSendResult, type InboxTag, type InboxTagResult, type InboxThread, type IntelligenceData, type IntentCompany, type IntentContact, type IntentKeyword, type IntentPage, type IntentSignals, type IntentStats, type IntentVisitor, KNOWN_WEBHOOK_EVENTS, type ListContact, type MarketplaceHiring, type MarketplaceOffer, type MarketplaceProfile, type MeetingAnalysis, type MeetingAttendee, type MeetingDetail, type MeetingListParams, type MeetingSummary, type MeetingTranscriptLine, type MissedCallback, type MissedCallbacksResult, type NodeTypeSchema, type Note, type PaginatedResponse, type PaginationMeta$1 as PaginationMeta, type PersonEnrichment, type Persona, type Pipeline, type PipelineStage, type PipelineSuggestion, type QuotableProduct, type QuoteCreateParams, type QuoteDetail, type QuoteLineItem, type QuoteListParams, type QuoteSendParams, type QuoteSettings, type QuoteStatus, type QuoteSummary, type QuoteUpdateParams, type RequestOptions, type ResearchReport, type SearchCompanyItem, type SearchCondition, type SearchContactItem, type SearchFilter, type SearchOperator, type SearchParams, type SearchResults, type SearchSaveParams, type SearchSaveResult, type Sequence, type SequenceActionResult, type SequenceAnalytics, type SequenceChannelConfig, type SequenceContactItem, type SequenceContactsParams, type SequenceCreateParams, type SequenceCreateResult, type SequenceDetail, type SequenceKind, type SequenceListItem, type SequenceListParams, type SequencePreview, type SequencePreviewChannel, type SequencePreviewStep, type SequenceStepConfig, type SequenceStepInputType, type SequenceStepType, type SequenceStepUpdateParams, type SequenceUpdateParams, type SetFieldValueParams, type Skill, type SkillCreateAPIParams, type SkillCreateLLMParams, type SkillInputField, type SkillListParams, type SkillTemplate, type SkillType, type SkillUpdateAPIParams, type SkillUpdateLLMParams, type Snippet, type StageCreateParams, type StagePipeline, type StagePipelineCreateParams, type StagePipelineStage, type StagePipelineUpdateParams, type StageUpdateParams, type Task, type TaskCreateParams, type TaskListParams, type TaskUpdateParams, type TimeSlot, type TokenManager, type TrackProperties, type VisitorCompany, type VisitorScore, type VoicePagination, type WebhookEvent, type WebhookEventPayload, WebhookSignatureError, type Workflow, type WorkflowConfig, type WorkflowConnection, type WorkflowCreateParams, type WorkflowExecution, type WorkflowListParams, type WorkflowNode, type WorkflowUpdateParams, backoffDelayMs, constructEvent, createAppRequester, createGraph8AppClient, createGraph8ServiceClient, createTokenManager, exchangeBrowserToken, exchangeServiceToken, g8, isRetryableStatus, paginate, parseRetryAfter, request };