@topolo/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,277 @@
+/**
+ * Auth credential types used by the SDK.
+ *
+ * Phase 1 supports two modes:
+ *   - `api_key`: a single platform API key (service-scoped at issuance).
+ *     Preferred for long-lived agent installs.
+ *   - `access_token`: a short-lived JWT from the interactive login flow.
+ *     Used by TopoloCli after `topolo auth login`.
+ *
+ * Phase 2 will add OAuth access tokens issued by the authorization-code +
+ * PKCE flow in TopoloAuth. Those will plug in as a third variant.
+ */
+type TopoloCredential = {
+    kind: 'api_key';
+    apiKey: string;
+} | {
+    kind: 'access_token';
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+};
+interface AgentIdentity {
+    /** Display name of the agent or tool making requests. Included in audit headers. */
+    clientName: string;
+    /** Semver of the client. Included in audit headers. */
+    clientVersion: string;
+    /**
+     * Optional agent-assigned label (e.g. "claude-code", "codex-cli") used for
+     * multi-tenant audit attribution when the client is used by another agent.
+     */
+    agentName?: string;
+}
+
+/**
+ * Service registry — base URLs for each Topolo platform service.
+ *
+ * Defaults point at production. Any entry can be overridden per-call via
+ * `TopoloClient` options, or globally via env vars like `TOPOLO_SERVICE_URL_CRM`.
+ *
+ * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
+ * scoped to the organization embedded in the auth credential (JWT claim or
+ * API-key binding). This is the load-bearing cross-org isolation guarantee.
+ */
+type ServiceId = 'auth' | 'crm';
+declare const DEFAULT_SERVICE_URLS: Record<ServiceId, string>;
+/**
+ * Service IDs as registered in TopoloAuth's service catalog. These are sent in
+ * the `X-Service-ID` header when the platform needs to route an API-key
+ * introspection or permission check.
+ */
+declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
+declare function resolveServiceUrl(service: ServiceId, overrides?: Partial<Record<ServiceId, string>>): string;
+
+interface TopoloClientOptions {
+    credential: TopoloCredential;
+    agent: AgentIdentity;
+    /** Per-service URL overrides. Useful for staging/dev. */
+    serviceUrls?: Partial<Record<ServiceId, string>>;
+    /**
+     * When true, mutating helpers (POST/PUT/PATCH/DELETE) require callers to pass
+     * `{ confirm: true }`. Defaults to true. Set false only for trusted surfaces.
+     */
+    requireConfirmForWrites?: boolean;
+    /** HTTP request timeout (ms). Default 30s. */
+    timeoutMs?: number;
+    /** Injected fetch, for testing. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+interface RequestOptions {
+    service: ServiceId;
+    path: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** Explicit write-acknowledgement for mutating calls. */
+    confirm?: boolean;
+    /** Extra headers appended after auth/audit headers. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+declare class TopoloClient {
+    private readonly credential;
+    private readonly agent;
+    private readonly serviceUrls?;
+    private readonly requireConfirmForWrites;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: TopoloClientOptions);
+    /**
+     * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
+     * for anything a caller would reach for; this stays exported for escape-hatch
+     * use and for the generic `topolo api` / MCP passthrough tool.
+     */
+    request<T = unknown>(opts: RequestOptions): Promise<T>;
+    /**
+     * Introspect the current credential. Returns the caller's resolved identity,
+     * organization, and permission set. Used by CLI `whoami` and by MCP to gate
+     * advertised tools by scope.
+     *
+     * Both JWT access tokens and platform API keys are resolved via the unified
+     * `GET /api/auth/me` endpoint on TopoloAuth, which does not require service
+     * credentials. The caller's possession of the credential secret is proof.
+     */
+    introspect(): Promise<CredentialIntrospection>;
+}
+interface CredentialIntrospection {
+    kind: 'api_key' | 'access_token';
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+        role: string;
+        permissions: string[];
+    };
+    organization: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+}
+
+declare class TopoloSdkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+declare class TopoloAuthError extends TopoloSdkError {
+    constructor(message: string, code?: string);
+}
+declare class TopoloPermissionError extends TopoloSdkError {
+    readonly required: string[];
+    constructor(message: string, required: string[]);
+}
+declare class TopoloHttpError extends TopoloSdkError {
+    readonly status: number;
+    readonly body: unknown;
+    readonly service: string;
+    readonly path: string;
+    constructor(service: string, path: string, status: number, body: unknown, message?: string);
+}
+
+interface CrmContactSummary {
+    id: string;
+    firstName: string | null;
+    lastName: string | null;
+    email: string | null;
+    phone: string | null;
+    company: string | null;
+    leadStatus: string | null;
+    lifecycleStage: string | null;
+    updatedAt: string | null;
+}
+interface ListContactsOptions {
+    /** Full-text search string. */
+    q?: string;
+    /** Page number, 1-indexed. */
+    page?: number;
+    /** Page size. */
+    pageSize?: number;
+}
+interface ListContactsResult {
+    contacts: CrmContactSummary[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/**
+ * CRM module — thin typed wrapper over the TopoloCRM HTTP API.
+ *
+ * Cross-org isolation: there is intentionally NO `orgId` parameter anywhere in
+ * this module. The organization is derived entirely from the auth credential
+ * by the CRM backend, which scopes all SQL queries by `org_slug`/`org_id`.
+ */
+declare class CrmModule {
+    private readonly client;
+    constructor(client: TopoloClient);
+    listContacts(options?: ListContactsOptions): Promise<ListContactsResult>;
+    getContact(contactId: string): Promise<CrmContactSummary | null>;
+}
+
+/**
+ * Identity module — wraps TopoloAuth's caller-identity endpoints.
+ *
+ * All responses are scoped to the organization the credential was issued for;
+ * there is no way to ask this module about a different org.
+ */
+declare class IdentityModule {
+    private readonly client;
+    constructor(client: TopoloClient);
+    /** Returns the resolved user, organization, and permission set for the
+     *  current credential. Equivalent to `TopoloClient.introspect()` — exposed
+     *  on this module for symmetry with the other domain modules. */
+    whoami(): Promise<CredentialIntrospection>;
+}
+
+interface DeviceAuthorizationResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    refresh_token?: string;
+    scope?: string;
+}
+interface OAuthHelperOptions {
+    /** Overrides for TopoloAuth URL. Staging/dev should pass a mapping. */
+    serviceUrls?: Partial<Record<ServiceId, string>>;
+    /** Injected fetch. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Thin client over the Topolo OAuth 2.1 authorization server. Intended for
+ * first-party tooling (the CLI) and registered third-party agents. Issued
+ * access tokens plug into `createTopolo({ credential: { kind: 'access_token', ... } })`.
+ */
+declare class TopoloOAuth {
+    #private;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: OAuthHelperOptions);
+    /**
+     * RFC 8628 device authorization grant — starts the flow by asking the server
+     * for a device_code + user_code. The caller prints the user_code +
+     * verification_uri and then polls `pollDeviceToken` until approval.
+     */
+    requestDeviceCode(params: {
+        clientId: string;
+        scope?: string | string[];
+    }): Promise<DeviceAuthorizationResponse>;
+    /**
+     * Polls the token endpoint once. Returns the token pair on success, or
+     * throws a `TopoloAuthError` whose `code` is one of the RFC 8628 poll
+     * states: `authorization_pending`, `slow_down`, `access_denied`,
+     * `expired_token`. Callers should back off on `slow_down`, wait at least
+     * one `interval` on `authorization_pending`, and give up on the rest.
+     */
+    pollDeviceToken(params: {
+        clientId: string;
+        deviceCode: string;
+        clientSecret?: string;
+    }): Promise<TokenResponse>;
+    /** Exchange an authorization code (with PKCE) for tokens. */
+    exchangeAuthorizationCode(params: {
+        clientId: string;
+        code: string;
+        redirectUri: string;
+        codeVerifier?: string;
+        clientSecret?: string;
+    }): Promise<TokenResponse>;
+    /** Rotate a refresh token for a new token pair. */
+    refreshToken(params: {
+        clientId: string;
+        refreshToken: string;
+        clientSecret?: string;
+    }): Promise<TokenResponse>;
+}
+
+/**
+ * Convenience factory that returns a ready-to-use typed Topolo client plus
+ * domain module surfaces (identity, crm, ...).
+ *
+ * Phase 1 exposes identity + crm; subsequent phases add more modules
+ * incrementally as each app's API contract stabilizes.
+ */
+declare function createTopolo(options: TopoloClientOptions): {
+    client: TopoloClient;
+    identity: IdentityModule;
+    crm: CrmModule;
+};
+type Topolo = ReturnType<typeof createTopolo>;
+
+export { type AgentIdentity, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, PLATFORM_SERVICE_IDS, type RequestOptions, type ServiceId, type TokenResponse, type Topolo, TopoloAuthError, TopoloClient, type TopoloClientOptions, type TopoloCredential, TopoloHttpError, TopoloOAuth, TopoloPermissionError, TopoloSdkError, createTopolo, resolveServiceUrl };

package/dist/index.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Auth credential types used by the SDK.
+ *
+ * Phase 1 supports two modes:
+ *   - `api_key`: a single platform API key (service-scoped at issuance).
+ *     Preferred for long-lived agent installs.
+ *   - `access_token`: a short-lived JWT from the interactive login flow.
+ *     Used by TopoloCli after `topolo auth login`.
+ *
+ * Phase 2 will add OAuth access tokens issued by the authorization-code +
+ * PKCE flow in TopoloAuth. Those will plug in as a third variant.
+ */
+type TopoloCredential = {
+    kind: 'api_key';
+    apiKey: string;
+} | {
+    kind: 'access_token';
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+};
+interface AgentIdentity {
+    /** Display name of the agent or tool making requests. Included in audit headers. */
+    clientName: string;
+    /** Semver of the client. Included in audit headers. */
+    clientVersion: string;
+    /**
+     * Optional agent-assigned label (e.g. "claude-code", "codex-cli") used for
+     * multi-tenant audit attribution when the client is used by another agent.
+     */
+    agentName?: string;
+}
+
+/**
+ * Service registry — base URLs for each Topolo platform service.
+ *
+ * Defaults point at production. Any entry can be overridden per-call via
+ * `TopoloClient` options, or globally via env vars like `TOPOLO_SERVICE_URL_CRM`.
+ *
+ * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
+ * scoped to the organization embedded in the auth credential (JWT claim or
+ * API-key binding). This is the load-bearing cross-org isolation guarantee.
+ */
+type ServiceId = 'auth' | 'crm';
+declare const DEFAULT_SERVICE_URLS: Record<ServiceId, string>;
+/**
+ * Service IDs as registered in TopoloAuth's service catalog. These are sent in
+ * the `X-Service-ID` header when the platform needs to route an API-key
+ * introspection or permission check.
+ */
+declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
+declare function resolveServiceUrl(service: ServiceId, overrides?: Partial<Record<ServiceId, string>>): string;
+
+interface TopoloClientOptions {
+    credential: TopoloCredential;
+    agent: AgentIdentity;
+    /** Per-service URL overrides. Useful for staging/dev. */
+    serviceUrls?: Partial<Record<ServiceId, string>>;
+    /**
+     * When true, mutating helpers (POST/PUT/PATCH/DELETE) require callers to pass
+     * `{ confirm: true }`. Defaults to true. Set false only for trusted surfaces.
+     */
+    requireConfirmForWrites?: boolean;
+    /** HTTP request timeout (ms). Default 30s. */
+    timeoutMs?: number;
+    /** Injected fetch, for testing. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+interface RequestOptions {
+    service: ServiceId;
+    path: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** Explicit write-acknowledgement for mutating calls. */
+    confirm?: boolean;
+    /** Extra headers appended after auth/audit headers. */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+declare class TopoloClient {
+    private readonly credential;
+    private readonly agent;
+    private readonly serviceUrls?;
+    private readonly requireConfirmForWrites;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: TopoloClientOptions);
+    /**
+     * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
+     * for anything a caller would reach for; this stays exported for escape-hatch
+     * use and for the generic `topolo api` / MCP passthrough tool.
+     */
+    request<T = unknown>(opts: RequestOptions): Promise<T>;
+    /**
+     * Introspect the current credential. Returns the caller's resolved identity,
+     * organization, and permission set. Used by CLI `whoami` and by MCP to gate
+     * advertised tools by scope.
+     *
+     * Both JWT access tokens and platform API keys are resolved via the unified
+     * `GET /api/auth/me` endpoint on TopoloAuth, which does not require service
+     * credentials. The caller's possession of the credential secret is proof.
+     */
+    introspect(): Promise<CredentialIntrospection>;
+}
+interface CredentialIntrospection {
+    kind: 'api_key' | 'access_token';
+    user: {
+        id: string;
+        email: string;
+        name: string | null;
+        role: string;
+        permissions: string[];
+    };
+    organization: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+}
+
+declare class TopoloSdkError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+declare class TopoloAuthError extends TopoloSdkError {
+    constructor(message: string, code?: string);
+}
+declare class TopoloPermissionError extends TopoloSdkError {
+    readonly required: string[];
+    constructor(message: string, required: string[]);
+}
+declare class TopoloHttpError extends TopoloSdkError {
+    readonly status: number;
+    readonly body: unknown;
+    readonly service: string;
+    readonly path: string;
+    constructor(service: string, path: string, status: number, body: unknown, message?: string);
+}
+
+interface CrmContactSummary {
+    id: string;
+    firstName: string | null;
+    lastName: string | null;
+    email: string | null;
+    phone: string | null;
+    company: string | null;
+    leadStatus: string | null;
+    lifecycleStage: string | null;
+    updatedAt: string | null;
+}
+interface ListContactsOptions {
+    /** Full-text search string. */
+    q?: string;
+    /** Page number, 1-indexed. */
+    page?: number;
+    /** Page size. */
+    pageSize?: number;
+}
+interface ListContactsResult {
+    contacts: CrmContactSummary[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/**
+ * CRM module — thin typed wrapper over the TopoloCRM HTTP API.
+ *
+ * Cross-org isolation: there is intentionally NO `orgId` parameter anywhere in
+ * this module. The organization is derived entirely from the auth credential
+ * by the CRM backend, which scopes all SQL queries by `org_slug`/`org_id`.
+ */
+declare class CrmModule {
+    private readonly client;
+    constructor(client: TopoloClient);
+    listContacts(options?: ListContactsOptions): Promise<ListContactsResult>;
+    getContact(contactId: string): Promise<CrmContactSummary | null>;
+}
+
+/**
+ * Identity module — wraps TopoloAuth's caller-identity endpoints.
+ *
+ * All responses are scoped to the organization the credential was issued for;
+ * there is no way to ask this module about a different org.
+ */
+declare class IdentityModule {
+    private readonly client;
+    constructor(client: TopoloClient);
+    /** Returns the resolved user, organization, and permission set for the
+     *  current credential. Equivalent to `TopoloClient.introspect()` — exposed
+     *  on this module for symmetry with the other domain modules. */
+    whoami(): Promise<CredentialIntrospection>;
+}
+
+interface DeviceAuthorizationResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    refresh_token?: string;
+    scope?: string;
+}
+interface OAuthHelperOptions {
+    /** Overrides for TopoloAuth URL. Staging/dev should pass a mapping. */
+    serviceUrls?: Partial<Record<ServiceId, string>>;
+    /** Injected fetch. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Thin client over the Topolo OAuth 2.1 authorization server. Intended for
+ * first-party tooling (the CLI) and registered third-party agents. Issued
+ * access tokens plug into `createTopolo({ credential: { kind: 'access_token', ... } })`.
+ */
+declare class TopoloOAuth {
+    #private;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options?: OAuthHelperOptions);
+    /**
+     * RFC 8628 device authorization grant — starts the flow by asking the server
+     * for a device_code + user_code. The caller prints the user_code +
+     * verification_uri and then polls `pollDeviceToken` until approval.
+     */
+    requestDeviceCode(params: {
+        clientId: string;
+        scope?: string | string[];
+    }): Promise<DeviceAuthorizationResponse>;
+    /**
+     * Polls the token endpoint once. Returns the token pair on success, or
+     * throws a `TopoloAuthError` whose `code` is one of the RFC 8628 poll
+     * states: `authorization_pending`, `slow_down`, `access_denied`,
+     * `expired_token`. Callers should back off on `slow_down`, wait at least
+     * one `interval` on `authorization_pending`, and give up on the rest.
+     */
+    pollDeviceToken(params: {
+        clientId: string;
+        deviceCode: string;
+        clientSecret?: string;
+    }): Promise<TokenResponse>;
+    /** Exchange an authorization code (with PKCE) for tokens. */
+    exchangeAuthorizationCode(params: {
+        clientId: string;
+        code: string;
+        redirectUri: string;
+        codeVerifier?: string;
+        clientSecret?: string;
+    }): Promise<TokenResponse>;
+    /** Rotate a refresh token for a new token pair. */
+    refreshToken(params: {
+        clientId: string;
+        refreshToken: string;
+        clientSecret?: string;
+    }): Promise<TokenResponse>;
+}
+
+/**
+ * Convenience factory that returns a ready-to-use typed Topolo client plus
+ * domain module surfaces (identity, crm, ...).
+ *
+ * Phase 1 exposes identity + crm; subsequent phases add more modules
+ * incrementally as each app's API contract stabilizes.
+ */
+declare function createTopolo(options: TopoloClientOptions): {
+    client: TopoloClient;
+    identity: IdentityModule;
+    crm: CrmModule;
+};
+type Topolo = ReturnType<typeof createTopolo>;
+
+export { type AgentIdentity, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, PLATFORM_SERVICE_IDS, type RequestOptions, type ServiceId, type TokenResponse, type Topolo, TopoloAuthError, TopoloClient, type TopoloClientOptions, type TopoloCredential, TopoloHttpError, TopoloOAuth, TopoloPermissionError, TopoloSdkError, createTopolo, resolveServiceUrl };