@topolo/sdk 0.1.0

package/src/errors.ts

@@ -0,0 +1,39 @@
+export class TopoloSdkError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'TopoloSdkError';
+    this.code = code;
+  }
+}
+
+export class TopoloAuthError extends TopoloSdkError {
+  constructor(message: string, code: string = 'auth_error') {
+    super(code, message);
+    this.name = 'TopoloAuthError';
+  }
+}
+
+export class TopoloPermissionError extends TopoloSdkError {
+  readonly required: string[];
+  constructor(message: string, required: string[]) {
+    super('permission_denied', message);
+    this.name = 'TopoloPermissionError';
+    this.required = required;
+  }
+}
+
+export 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) {
+    super('http_error', message ?? `HTTP ${status} from ${service}${path}`);
+    this.name = 'TopoloHttpError';
+    this.status = status;
+    this.body = body;
+    this.service = service;
+    this.path = path;
+  }
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export {
+  TopoloClient,
+  type TopoloClientOptions,
+  type RequestOptions,
+  type CredentialIntrospection,
+} from './client.js';
+export type { TopoloCredential, AgentIdentity } from './auth.js';
+export {
+  DEFAULT_SERVICE_URLS,
+  PLATFORM_SERVICE_IDS,
+  resolveServiceUrl,
+  type ServiceId,
+} from './services.js';
+export {
+  TopoloSdkError,
+  TopoloAuthError,
+  TopoloPermissionError,
+  TopoloHttpError,
+} from './errors.js';
+export { CrmModule, type CrmContactSummary, type ListContactsOptions, type ListContactsResult } from './modules/crm.js';
+export { IdentityModule } from './modules/identity.js';
+export {
+  TopoloOAuth,
+  type OAuthHelperOptions,
+  type DeviceAuthorizationResponse,
+  type TokenResponse,
+} from './oauth.js';
+
+import { TopoloClient, type TopoloClientOptions } from './client.js';
+import { CrmModule } from './modules/crm.js';
+import { IdentityModule } from './modules/identity.js';
+
+/**
+ * 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.
+ */
+export function createTopolo(options: TopoloClientOptions) {
+  const client = new TopoloClient(options);
+  return {
+    client,
+    identity: new IdentityModule(client),
+    crm: new CrmModule(client),
+  };
+}
+
+export type Topolo = ReturnType<typeof createTopolo>;

package/src/modules/crm.ts

@@ -0,0 +1,110 @@
+import type { TopoloClient } from '../client.js';
+
+export 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;
+}
+
+export interface ListContactsOptions {
+  /** Full-text search string. */
+  q?: string;
+  /** Page number, 1-indexed. */
+  page?: number;
+  /** Page size. */
+  pageSize?: number;
+}
+
+export 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`.
+ */
+export class CrmModule {
+  constructor(private readonly client: TopoloClient) {}
+
+  async listContacts(options: ListContactsOptions = {}): Promise<ListContactsResult> {
+    const res = await this.client.request<RawListResponse>({
+      service: 'crm',
+      path: '/api/contacts',
+      query: {
+        q: options.q,
+        page: options.page,
+        pageSize: options.pageSize,
+      },
+    });
+
+    const rows = Array.isArray(res?.contacts)
+      ? res.contacts
+      : Array.isArray(res?.data)
+        ? res.data
+        : [];
+
+    return {
+      contacts: rows.map(toSummary),
+      total: res?.total ?? res?.pagination?.total ?? rows.length,
+      page: res?.page ?? res?.pagination?.page ?? options.page ?? 1,
+      pageSize: res?.pageSize ?? res?.pagination?.pageSize ?? options.pageSize ?? rows.length,
+    };
+  }
+
+  async getContact(contactId: string): Promise<CrmContactSummary | null> {
+    if (!contactId) throw new Error('contactId is required');
+    const res = await this.client.request<{ data?: RawContact } | RawContact>({
+      service: 'crm',
+      path: `/api/contacts/${encodeURIComponent(contactId)}`,
+    });
+    const row = (res as { data?: RawContact }).data ?? (res as RawContact);
+    return row ? toSummary(row) : null;
+  }
+}
+
+interface RawContact {
+  id: string;
+  first?: string | null;
+  last?: string | null;
+  email?: string | null;
+  phone?: string | null;
+  company?: string | null;
+  lead_status?: string | null;
+  lifecycle_stage?: string | null;
+  updated_at?: string | null;
+}
+
+interface RawListResponse {
+  contacts?: RawContact[];
+  data?: RawContact[];
+  total?: number;
+  page?: number;
+  pageSize?: number;
+  pagination?: { total?: number; page?: number; pageSize?: number };
+}
+
+function toSummary(row: RawContact): CrmContactSummary {
+  return {
+    id: row.id,
+    firstName: row.first ?? null,
+    lastName: row.last ?? null,
+    email: row.email ?? null,
+    phone: row.phone ?? null,
+    company: row.company ?? null,
+    leadStatus: row.lead_status ?? null,
+    lifecycleStage: row.lifecycle_stage ?? null,
+    updatedAt: row.updated_at ?? null,
+  };
+}

package/src/modules/identity.ts

@@ -0,0 +1,18 @@
+import type { CredentialIntrospection, TopoloClient } from '../client.js';
+
+/**
+ * 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.
+ */
+export class IdentityModule {
+  constructor(private readonly 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> {
+    return this.client.introspect();
+  }
+}

package/src/oauth.ts

@@ -0,0 +1,138 @@
+import { TopoloAuthError, TopoloHttpError } from './errors.js';
+import { resolveServiceUrl, type ServiceId } from './services.js';
+
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+
+export interface DeviceAuthorizationResponse {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  verification_uri_complete?: string;
+  expires_in: number;
+  interval: number;
+}
+
+export interface TokenResponse {
+  access_token: string;
+  token_type: 'Bearer';
+  expires_in: number;
+  refresh_token?: string;
+  scope?: string;
+}
+
+export 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', ... } })`.
+ */
+export class TopoloOAuth {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: OAuthHelperOptions = {}) {
+    this.baseUrl = resolveServiceUrl('auth', options.serviceUrls);
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  /**
+   * 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.
+   */
+  async requestDeviceCode(params: {
+    clientId: string;
+    scope?: string | string[];
+  }): Promise<DeviceAuthorizationResponse> {
+    const body = new URLSearchParams();
+    body.set('client_id', params.clientId);
+    if (params.scope) {
+      body.set('scope', Array.isArray(params.scope) ? params.scope.join(' ') : params.scope);
+    }
+    return this.#postForm('/api/developer-oauth/device_authorization', body);
+  }
+
+  /**
+   * 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.
+   */
+  async pollDeviceToken(params: {
+    clientId: string;
+    deviceCode: string;
+    clientSecret?: string;
+  }): Promise<TokenResponse> {
+    const body = new URLSearchParams();
+    body.set('grant_type', DEVICE_GRANT);
+    body.set('client_id', params.clientId);
+    body.set('device_code', params.deviceCode);
+    if (params.clientSecret) body.set('client_secret', params.clientSecret);
+    return this.#postForm('/api/developer-oauth/token', body);
+  }
+
+  /** Exchange an authorization code (with PKCE) for tokens. */
+  async exchangeAuthorizationCode(params: {
+    clientId: string;
+    code: string;
+    redirectUri: string;
+    codeVerifier?: string;
+    clientSecret?: string;
+  }): Promise<TokenResponse> {
+    const body = new URLSearchParams();
+    body.set('grant_type', 'authorization_code');
+    body.set('client_id', params.clientId);
+    body.set('code', params.code);
+    body.set('redirect_uri', params.redirectUri);
+    if (params.codeVerifier) body.set('code_verifier', params.codeVerifier);
+    if (params.clientSecret) body.set('client_secret', params.clientSecret);
+    return this.#postForm('/api/developer-oauth/token', body);
+  }
+
+  /** Rotate a refresh token for a new token pair. */
+  async refreshToken(params: {
+    clientId: string;
+    refreshToken: string;
+    clientSecret?: string;
+  }): Promise<TokenResponse> {
+    const body = new URLSearchParams();
+    body.set('grant_type', 'refresh_token');
+    body.set('client_id', params.clientId);
+    body.set('refresh_token', params.refreshToken);
+    if (params.clientSecret) body.set('client_secret', params.clientSecret);
+    return this.#postForm('/api/developer-oauth/token', body);
+  }
+
+  async #postForm<T>(path: string, body: URLSearchParams): Promise<T> {
+    const url = new URL(path, this.baseUrl.endsWith('/') ? this.baseUrl : `${this.baseUrl}/`);
+    const res = await this.fetchImpl(url.toString(), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+      body: body.toString(),
+    });
+
+    const contentType = res.headers.get('Content-Type') ?? '';
+    const parsed: unknown = contentType.includes('application/json')
+      ? await res.json().catch(() => null)
+      : await res.text().catch(() => null);
+
+    if (!res.ok) {
+      if (parsed && typeof parsed === 'object' && 'error' in parsed) {
+        const err = parsed as { error: string; error_description?: string };
+        throw new TopoloAuthError(err.error_description || err.error, err.error);
+      }
+      throw new TopoloHttpError('auth', path, res.status, parsed);
+    }
+    return parsed as T;
+  }
+}

package/src/services.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export type ServiceId =
+  | 'auth'
+  | 'crm';
+
+export const DEFAULT_SERVICE_URLS: Record<ServiceId, string> = {
+  auth: 'https://auth.topolo.app',
+  crm: 'https://topolo-crm-worker.topolo.workers.dev',
+};
+
+/**
+ * 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.
+ */
+export const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>> = {
+  crm: 'srv_iCwM4jGXcwlj',
+};
+
+export function resolveServiceUrl(
+  service: ServiceId,
+  overrides?: Partial<Record<ServiceId, string>>,
+): string {
+  const override = overrides?.[service];
+  if (override) return override;
+
+  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
+  if (envValue) return envValue;
+
+  return DEFAULT_SERVICE_URLS[service];
+}