@oneplatform/sdk — L2 Package Design¶

// Public API surface exported from @oneplatform/sdk
export { createClient } from './client';

// Error types — all exported for instanceof checks
export {
  OnePlatformError,
  ClientError,
  AuthError,
  NotFoundError,
  ValidationError,
  ConflictError,
  ForbiddenError,
  RateLimitError,
  ServerError,
  NetworkError,
  CursorExpiredError,
} from './errors';

// Pagination types
export type { Page, PaginatedIterable, PaginationOptions } from './pagination';

// Subscription types
export type { Subscription, PlatformEvent, SubscriptionOptions } from './subscriptions';

// Client option types
export type {
  ClientOptions,
  RetryPolicy,
  AuthConfig,
  ApiKeyAuthConfig,
  AccessTokenAuthConfig,
  BrowserAuthConfig,
} from './types/client-options';

// Filter/sort builder for advanced queries
export { filter } from './filter-builder';
export type { FilterBuilder, SortSpec } from './filter-builder';

function createClient(options: ClientOptions): OnePlatformClient

interface ClientOptions {
  /**
   * Base URL of the OnePlatform instance.
   * Examples:
   *   "https://platform.example.com"
   *   "http://localhost:3000"  (local development)
   * Must NOT have a trailing slash.
   * Required.
   */
  baseUrl: string;

  /**
   * Authentication configuration.
   * Exactly one of: apiKey, accessToken, or browser must be provided.
   * If omitted entirely, the SDK auto-detects the environment:
   *   - Browser environment → starts browser PKCE flow
   *   - Node.js environment → throws ConfigurationError (explicit auth required)
   */
  auth?: AuthConfig;

  /**
   * Retry policy. Defaults applied if omitted.
   * Set to false to disable all retry logic.
   */
  retry?: RetryPolicy | false;

  /**
   * Request timeout in milliseconds. Default: 30000 (30s).
   * Applies to each individual HTTP request (not the total retry sequence).
   * Set to 0 to disable timeout (not recommended).
   */
  timeout?: number;

  /**
   * Custom fetch implementation.
   * Defaults to globalThis.fetch.
   * Useful for testing (inject a mock) or environments where fetch needs configuration.
   */
  fetch?: typeof globalThis.fetch;

  /**
   * Custom headers to include on every request.
   * Merged with SDK-managed headers (Authorization, Content-Type, Accept).
   * SDK-managed headers take precedence if keys conflict.
   */
  headers?: Record<string, string>;

  /**
   * Log level for SDK-internal diagnostic messages.
   * These go to console.debug/info/warn/error.
   * Default: 'warn'.
   */
  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
}

interface RetryPolicy {
  /**
   * Maximum number of retry attempts (not counting the initial attempt).
   * Default: 3.
   */
  maxRetries?: number;

  /**
   * Initial backoff delay in milliseconds.
   * Each retry doubles this value (exponential).
   * Default: 500ms.
   */
  initialDelayMs?: number;

  /**
   * Maximum backoff delay cap in milliseconds.
   * Prevents exponential runaway on many retries.
   * Default: 30000ms (30s).
   */
  maxDelayMs?: number;

  /**
   * HTTP status codes that trigger a retry.
   * Default: [429, 500, 502, 503, 504].
   * 429 always uses the Retry-After header if present, regardless of backoff calculation.
   */
  retryableStatusCodes?: number[];

  /**
   * Whether to add ±25% random jitter to the backoff delay.
   * Prevents thundering-herd from many clients retrying simultaneously.
   * Default: true.
   */
  jitter?: boolean;
}

interface OnePlatformClient {
  // Data access (ontology-typed entities)
  data: DataNamespace;

  // Pipeline management
  pipelines: PipelineNamespace;

  // Connector management
  connectors: ConnectorNamespace;

  // Ontology schema management
  ontologies: OntologyNamespace;

  // Real-time event subscriptions
  events: EventNamespace;

  // App management
  apps: AppNamespace;

  // Plugin management
  plugins: PluginNamespace;

  // API key management
  apiKeys: ApiKeyNamespace;

  // User management (admin-only operations)
  users: UserNamespace;

  // Log and audit queries
  logs: LogNamespace;

  /**
   * Returns the resolved options this client was created with.
   * Auth tokens are redacted. Useful for debugging.
   */
  getConfig(): Readonly<ResolvedClientConfig>;

  /**
   * Checks platform connectivity and auth.
   * Makes a GET /api/v1/auth/whoami request.
   * Resolves with the current user identity or throws an error.
   */
  ping(): Promise<WhoAmIResponse>;

  /**
   * Cleanly terminates all active SSE subscriptions and in-flight requests.
   * After calling destroy(), the client must not be reused.
   */
  destroy(): void;
}

import { createClient } from '@oneplatform/sdk';

// Server-side: API key auth
const client = createClient({
  baseUrl: 'https://platform.example.com',
  auth: { apiKey: 'op_live_abc123...' },
  timeout: 15000,
  retry: { maxRetries: 3, initialDelayMs: 500 },
});

// Server-side: existing access token (e.g., forwarded from a user session)
const client = createClient({
  baseUrl: 'https://platform.example.com',
  auth: { accessToken: userJwt },
});

// Browser: PKCE flow (auth is automatic)
const client = createClient({
  baseUrl: 'https://platform.example.com',
  auth: { browser: { clientId: 'app:my-app:tenant-id' } },
});

type AuthConfig =
  | ApiKeyAuthConfig
  | AccessTokenAuthConfig
  | BrowserAuthConfig;

interface ApiKeyAuthConfig {
  apiKey: string;
}

interface AccessTokenAuthConfig {
  /**
   * A JWT access token previously obtained from the Auth Service.
   * The SDK sends it as-is and does NOT attempt token refresh.
   * When the token expires, requests will fail with AuthError.
   * The caller is responsible for refreshing and calling client.setAccessToken().
   */
  accessToken: string;

  /**
   * Optional callback invoked when a request fails with 401 Unauthorized.
   * The SDK calls this to fetch a fresh token.
   * If provided, the SDK will retry the failed request once with the new token.
   * If this callback throws or returns null, the original AuthError is propagated.
   */
  refreshToken?: () => Promise<string | null>;
}

interface BrowserAuthConfig {
  /**
   * OAuth client ID registered with the platform Auth Service.
   * Format: "app:{appId}:{tenantId}"
   */
  clientId: string;

  /**
   * URI the browser is redirected to after the Auth Service grants the code.
   * Must match a registered redirect URI for this clientId.
   * Default: current window.location.origin + '/auth/callback'
   */
  redirectUri?: string;

  /**
   * Scopes to request. Default: ['openid', 'profile', 'data:read', 'data:write'].
   */
  scopes?: string[];

  /**
   * Storage key prefix for tokens in sessionStorage.
   * Default: 'op_sdk'.
   * Tokens are stored as 'op_sdk_access_token', 'op_sdk_refresh_token', etc.
   */
  storagePrefix?: string;
}

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), options.timeout ?? 30000);
const response = await fetch(url, { ...fetchOptions, signal: controller.signal });
clearTimeout(timeoutId);

function backoff(attemptNumber: number, policy: RetryPolicy): number {
  const base = policy.initialDelayMs * Math.pow(2, attemptNumber); // 500, 1000, 2000, 4000...
  const capped = Math.min(base, policy.maxDelayMs);

  if (!policy.jitter) return capped;

  // ±25% jitter
  const jitterFactor = 0.75 + Math.random() * 0.5; // 0.75 to 1.25
  return Math.floor(capped * jitterFactor);
}

function parseRetryAfter(header: string): number {
  const seconds = parseInt(header, 10);
  if (!isNaN(seconds)) {
    // Seconds format: "Retry-After: 30"
    return seconds * 1000;
  }
  // HTTP-date format: "Retry-After: Wed, 11 Jun 2026 00:00:00 GMT"
  const date = Date.parse(header);
  if (!isNaN(date)) {
    return Math.max(0, date - Date.now());
  }
  // Unparseable — fall back to normal backoff
  return backoff(currentAttempt, policy);
}

class OnePlatformError extends Error {
  /**
   * Platform error code (SCREAMING_SNAKE_CASE).
   * Examples: "ENTITY_NOT_FOUND", "RATE_LIMIT_EXCEEDED", "INTERNAL_ERROR"
   * "SDK_ERROR" for errors that never reached the server.
   */
  readonly code: string;

  /**
   * Human-readable message safe to display in a UI.
   * Does not include stack traces, internal paths, or platform internals.
   */
  readonly message: string;

  /**
   * HTTP status code from the server. Undefined for NetworkError and ConfigurationError.
   */
  readonly statusCode?: number;

  /**
   * Platform-assigned request ID. Present on all server errors.
   * Absent on NetworkError, ConfigurationError.
   * Provide to platform support for log correlation.
   */
  readonly requestId?: string;

  /**
   * Structured details from the server error body.
   * ValidationError uses details.fields: { fieldName: string[] } for per-field messages.
   */
  readonly details?: Record<string, unknown>;

  /**
   * Whether this error type is safe to retry.
   * RateLimitError, ServerError, NetworkError → true
   * ClientError subclasses → false
   */
  readonly retryable: boolean;

  /**
   * Original response object (if the error came from an HTTP response).
   * Useful for reading custom headers (e.g., X-RateLimit-Reset).
   */
  readonly response?: Response;
}

class ClientError extends OnePlatformError {
  readonly retryable = false;
}

class AuthError extends ClientError {
  readonly statusCode = 401;
  // code: "UNAUTHORIZED"
}

class ForbiddenError extends ClientError {
  readonly statusCode = 403;
  // code: "FORBIDDEN" | "PERMISSION_DENIED" | "ORIGIN_NOT_ALLOWED"
}

class NotFoundError extends ClientError {
  readonly statusCode = 404;
  // code: "NOT_FOUND" | "ENTITY_NOT_FOUND"
}

class ConflictError extends ClientError {
  readonly statusCode = 409;
  // code: "CONFLICT"
}

class ValidationError extends ClientError {
  readonly statusCode = 422;
  // code: "VALIDATION_ERROR"
  // details.fields: Record<string, string[]> — per-field errors
  get fieldErrors(): Record<string, string[]> {
    return (this.details?.fields as Record<string, string[]>) ?? {};
  }
}

class CursorExpiredError extends ClientError {
  readonly statusCode = 410;
  // code: "CURSOR_EXPIRED"
  // Caller must restart pagination from the beginning
}

class ConfigurationError extends ClientError {
  // No statusCode — this error is never sent to the server
  // code: "SDK_CONFIGURATION_ERROR"
  readonly retryable = false;
}

class RateLimitError extends OnePlatformError {
  readonly statusCode = 429;
  readonly retryable = true;

  /**
   * Seconds until the rate limit resets.
   * Parsed from the Retry-After header.
   * null if the server did not provide a Retry-After value.
   */
  readonly retryAfterSeconds: number | null;
}

class ServerError extends OnePlatformError {
  // code: "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE" | any 5xx platform code
  readonly retryable = true;
}

class NetworkError extends OnePlatformError {
  readonly retryable = true;
  readonly code = 'SDK_NETWORK_ERROR';
  // No statusCode — request never reached the server (or response was never received)

  /**
   * Underlying cause.
   * 'timeout': AbortController fired before response arrived
   * 'fetch-failed': fetch() threw (DNS failure, connection refused, etc.)
   * 'parse-failed': response arrived but body parsing failed
   */
  readonly reason: 'timeout' | 'fetch-failed' | 'parse-failed';

  /**
   * Timeout duration in ms, if reason === 'timeout'.
   */
  readonly timeoutMs?: number;
}

async function mapResponseToError(response: Response): Promise<OnePlatformError> {
  let body: { error?: { code: string; message: string; details?: unknown; requestId?: string } };

  try {
    body = await response.json();
  } catch {
    // Response body is not JSON — construct a generic error
    return new ServerError({
      code: 'INTERNAL_ERROR',
      message: `Server returned ${response.status} with non-JSON body`,
      statusCode: response.status,
      response,
      retryable: response.status >= 500,
    });
  }

  const { code = 'UNKNOWN_ERROR', message = 'An unknown error occurred', details, requestId } = body.error ?? {};
  const base = { code, message, details, requestId, statusCode: response.status, response };

  switch (response.status) {
    case 400: return new ClientError(base);
    case 401: return new AuthError(base);
    case 403: return new ForbiddenError(base);
    case 404: return new NotFoundError(base);
    case 409: return new ConflictError(base);
    case 410: return new CursorExpiredError(base);
    case 422: return new ValidationError(base);
    case 429: return new RateLimitError({ ...base, retryAfterSeconds: parseRetryAfterSeconds(response) });
    default:
      if (response.status >= 500) return new ServerError(base);
      return new ClientError(base); // Unknown 4xx
  }
}

interface Page<T> {
  /**
   * The items on this page.
   */
  items: T[];

  /**
   * Opaque cursor for the next page.
   * null if this is the last page.
   */
  nextCursor: string | null;

  /**
   * Total matching items across all pages.
   * null for large collections where total computation is too expensive (>100k rows).
   */
  total: number | null;

  /**
   * Whether this is the last page (nextCursor === null).
   */
  hasMore: boolean;
}

interface PaginatedIterable<T> extends AsyncIterable<Page<T>> {
  /**
   * Collects all items across all pages into a flat array.
   * Iterates pages until nextCursor is null.
   *
   * @param maxItems - Hard cap on total collected items. Defaults to 10000.
   *   Throws PaginationLimitError if maxItems is exceeded and there are still more pages.
   *   This prevents unbounded memory consumption on misconfigured calls.
   * @returns Array of all items (up to maxItems).
   */
  collect(maxItems?: number): Promise<T[]>;

  /**
   * Collects exactly n items. Stops pagination early once n items are gathered.
   * Does not throw if the collection has fewer than n items — returns what's available.
   *
   * @param n - Number of items to return.
   */
  take(n: number): Promise<T[]>;

  /**
   * Returns just the first page.
   * Equivalent to: (await asyncIterator.next()).value
   */
  firstPage(): Promise<Page<T>>;
}

class Paginator<T> implements PaginatedIterable<T> {
  constructor(
    private readonly fetchPage: (cursor: string | null, limit: number) => Promise<Page<T>>,
    private readonly pageSize: number = 50,
  ) {}

  async *[Symbol.asyncIterator](): AsyncGenerator<Page<T>> {
    let cursor: string | null = null;
    do {
      const page = await this.fetchPage(cursor, this.pageSize);
      yield page;
      cursor = page.nextCursor;
    } while (cursor !== null);
  }

  async collect(maxItems = 10000): Promise<T[]> {
    const results: T[] = [];
    for await (const page of this) {
      results.push(...page.items);
      if (results.length >= maxItems) {
        if (page.hasMore) {
          throw new PaginationLimitError(
            `collect() stopped at ${maxItems} items. Pass a higher maxItems or use AsyncIterable iteration.`,
            maxItems,
          );
        }
        break;
      }
    }
    return results;
  }

  async take(n: number): Promise<T[]> {
    const results: T[] = [];
    for await (const page of this) {
      results.push(...page.items);
      if (results.length >= n) return results.slice(0, n);
    }
    return results;
  }

  async firstPage(): Promise<Page<T>> {
    const iter = this[Symbol.asyncIterator]();
    const first = await iter.next();
    return first.value;
  }
}

// Page-by-page iteration
for await (const page of client.data.Product.list()) {
  console.log(`Page of ${page.items.length}, total: ${page.total}`);
  for (const product of page.items) {
    process(product);
  }
}

// Collect all (up to default 10k limit)
const allProducts = await client.data.Product.list().collect();

// Collect up to 500 items
const recent = await client.data.Product.list({
  sort: '-createdAt',
}).collect(500);

// Take exactly 10
const first10 = await client.data.Product.list().take(10);

// First page only (no iteration)
const page1 = await client.data.Product.list().firstPage();
console.log(page1.items, page1.total);

interface PlatformEvent {
  /** Unique event ID. Used as Last-Event-ID for resumption. */
  id: string;

  /** Event type. Dot-separated hierarchy. Examples: "pipeline.run.completed", "data.created" */
  type: string;

  /** Tenant ID this event belongs to. */
  tenantId: string;

  /** ISO 8601 timestamp when the event occurred. */
  occurredAt: string;

  /** Event-specific payload. Type varies by event type. */
  payload: unknown;
}

interface SubscriptionOptions {
  /**
   * Event patterns to subscribe to.
   * Supports exact strings and prefix wildcards (trailing .*).
   * Examples:
   *   ["pipeline.run.completed"]            — specific event
   *   ["pipeline.*"]                        — all pipeline events
   *   ["data.created", "data.updated"]      — multiple specific events
   *   ["*"]                                 — all events (use sparingly)
   */
  events: string[];

  /**
   * Optional server-side filter applied before delivery.
   * Reduces unnecessary traffic for high-volume event streams.
   */
  filter?: {
    entityType?: string;
    entityId?: string;
    pipelineId?: string;
  };

  /**
   * If provided, the subscription resumes from this event ID.
   * The server replays any events after this ID (up to its replay window).
   * Automatically managed by the SDK on reconnection using Last-Event-ID.
   */
  fromEventId?: string;
}

interface Subscription {
  /**
   * The subscription ID assigned by the server.
   * Included in the first 'connected' event from the SSE stream.
   */
  readonly id: string;

  /**
   * Current connection status.
   */
  readonly status: 'connecting' | 'connected' | 'reconnecting' | 'closed';

  /**
   * The Last-Event-ID received. Used for reconnection resumption.
   */
  readonly lastEventId: string | null;

  /**
   * Terminates the subscription. The SSE connection is closed.
   * The event handler will not be called after unsubscribe().
   */
  unsubscribe(): void;

  /**
   * Emitted when the connection status changes.
   */
  on(event: 'status', handler: (status: Subscription['status']) => void): this;

  /**
   * Emitted when an error occurs (typically before a reconnect attempt).
   */
  on(event: 'error', handler: (error: NetworkError) => void): this;
}

const sub = client.events.subscribe(
  { events: ['pipeline.*'], filter: { entityType: 'Order' } },
  (event: PlatformEvent) => {
    console.log(event.type, event.payload);
  },
);

// Monitor status changes
sub.on('status', (status) => {
  if (status === 'reconnecting') console.warn('SSE reconnecting...');
});

// Clean up
sub.unsubscribe();

interface DataNamespace {
  /**
   * Access a typed entity resource by name.
   * Used with generated typed clients where EntityType is known at compile time.
   * Example: client.data.Product.list()
   */
  [entityType: string]: EntityResource<Record<string, unknown>>;

  /**
   * Generic entity access when type is not known at compile time.
   */
  entity(entityType: string): EntityResource<Record<string, unknown>>;
}

interface EntityResource<T> {
  list(options?: ListOptions): PaginatedIterable<T>;
  get(id: string, options?: GetOptions): Promise<T>;
  create(data: Partial<T>, options?: MutationOptions): Promise<T>;
  update(id: string, data: Partial<T>, options?: MutationOptions): Promise<T>;
  replace(id: string, data: T, options?: MutationOptions): Promise<T>;
  delete(id: string): Promise<void>;
  bulk(operation: BulkOperation<T>): Promise<BulkResult<T>>;
}

interface ListOptions {
  /**
   * Server page size. Default: 50. Max: 100.
   * Controls the page size for each server request, not the total collect() limit.
   */
  limit?: number;

  /**
   * Filter specification. Use the filter() builder for type-safe construction
   * or pass raw filter objects for dynamic use cases.
   *
   * Example using builder: filter('status').eq('active').and('price').gt(100)
   * Example raw: { 'filter[status][eq]': 'active', 'filter[price][gt]': '100' }
   */
  filter?: FilterBuilder | Record<string, string>;

  /**
   * Sort specification. Prefix with '-' for descending.
   * Example: '-createdAt' or ['name', '-price']
   */
  sort?: string | string[];

  /**
   * Fields to include in the response. Reduces payload size.
   * Unknown fields are silently ignored by the server.
   * Example: ['id', 'name', 'status']
   */
  fields?: string[];

  /**
   * Starting cursor for pagination. Usually managed by the Paginator automatically.
   * Pass explicitly only if resuming a previous pagination session.
   */
  cursor?: string;
}

// Construction via factory function
import { filter } from '@oneplatform/sdk';

const f = filter('status').eq('active')
  .and('price').gt(100)
  .and('tags').in(['featured', 'sale'])
  .and('deletedAt').null(true);

// Produces query params:
// filter[status][eq]=active&filter[price][gt]=100&filter[tags][in]=featured,sale&filter[deletedAt][null]=true

// Use in list()
client.data.Product.list({ filter: f });

interface FilterBuilder {
  // Chainable conditions
  and(field: string): FieldConditionBuilder;

  // Serializes to Record<string, string> for inclusion in query params
  toParams(): Record<string, string>;
}

interface FieldConditionBuilder extends FilterBuilder {
  eq(value: string | number | boolean): FilterBuilder;
  neq(value: string | number | boolean): FilterBuilder;
  gt(value: number | string): FilterBuilder;
  gte(value: number | string): FilterBuilder;
  lt(value: number | string): FilterBuilder;
  lte(value: number | string): FilterBuilder;
  like(pattern: string): FilterBuilder;
  in(values: Array<string | number>): FilterBuilder;
  null(isNull: boolean): FilterBuilder;
}

interface PipelineNamespace {
  list(options?: ListOptions): PaginatedIterable<Pipeline>;
  get(id: string): Promise<Pipeline>;
  create(data: CreatePipelineRequest): Promise<Pipeline>;
  update(id: string, data: UpdatePipelineRequest): Promise<Pipeline>;
  delete(id: string): Promise<void>;
  trigger(id: string, input?: Record<string, unknown>): Promise<PipelineRun>;
  getRun(pipelineId: string, runId: string): Promise<PipelineRun>;
  listRuns(pipelineId: string, options?: ListOptions): PaginatedIterable<PipelineRun>;
  cancelRun(pipelineId: string, runId: string): Promise<PipelineRun>;
  streamRunLogs(pipelineId: string, runId: string): PaginatedIterable<LogEntry>;
}

interface ConnectorNamespace {
  list(options?: ListOptions): PaginatedIterable<ConnectorInstance>;
  get(id: string): Promise<ConnectorInstance>;
  create(data: CreateConnectorRequest): Promise<ConnectorInstance>;
  update(id: string, data: UpdateConnectorRequest): Promise<ConnectorInstance>;
  delete(id: string): Promise<void>;
  test(id: string): Promise<ConnectorTestResult>;
  trigger(id: string): Promise<PipelineRun>;
}

interface OntologyNamespace {
  list(options?: ListOptions): PaginatedIterable<OntologySchema>;
  get(id: string): Promise<OntologySchema>;
  create(data: CreateOntologyRequest): Promise<OntologySchema>;
  update(id: string, data: UpdateOntologyRequest): Promise<OntologySchema>;
  delete(id: string): Promise<void>;
  validate(data: ValidateOntologyRequest): Promise<ValidationResult>;
  diff(fromVersion: string, toVersion: string): Promise<OntologyDiff>;
  getMigrationStatus(id: string): Promise<MigrationStatus>;
}

interface ApiKeyNamespace {
  list(options?: ListOptions): PaginatedIterable<ApiKey>;
  create(data: CreateApiKeyRequest): Promise<CreatedApiKey>; // Returns key value once
  revoke(id: string): Promise<void>;
  rotate(id: string): Promise<CreatedApiKey>; // Returns new key value once
}

interface LogNamespace {
  query(options: LogQueryOptions): PaginatedIterable<LogEntry>;
  tail(options?: TailOptions): PaginatedIterable<LogEntry>;
  queryAudit(options: AuditQueryOptions): PaginatedIterable<AuditEntry>;
}

// oneplatform.gen.ts
// AUTO-GENERATED by @oneplatform/cli sdk generate
// DO NOT EDIT MANUALLY — re-run `op sdk generate` to update
// Generated: 2026-06-10T12:00:00Z | Schema version: 42

import { createClient, type ClientOptions, type PaginatedIterable, type Page } from '@oneplatform/sdk';

// ============================================================
// Entity type definitions (from tenant ontology)
// ============================================================

export interface Product {
  id: string;
  name: string;
  status: 'active' | 'inactive' | 'draft';
  price: number;
  currency: string;
  tags: string[];
  data: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
}

export interface Order {
  id: string;
  status: 'pending' | 'fulfilled' | 'cancelled';
  customerId: string;
  items: OrderItem[];
  total: number;
  createdAt: string;
  updatedAt: string;
}

// ... (all tenant entity types)

// ============================================================
// Typed filter builders (per entity type)
// ============================================================

export interface ProductFilterBuilder {
  status: FieldConditionBuilder<'active' | 'inactive' | 'draft'>;
  price: NumericConditionBuilder;
  name: StringConditionBuilder;
  createdAt: DateConditionBuilder;
  // ... all indexed fields
}

// ============================================================
// Typed resource interfaces (per entity type)
// ============================================================

export interface TypedProductResource {
  list(options?: TypedListOptions<ProductFilterBuilder>): PaginatedIterable<Product>;
  get(id: string): Promise<Product>;
  create(data: Omit<Product, 'id' | 'createdAt' | 'updatedAt'>): Promise<Product>;
  update(id: string, data: Partial<Omit<Product, 'id' | 'createdAt' | 'updatedAt'>>): Promise<Product>;
  replace(id: string, data: Omit<Product, 'id' | 'createdAt' | 'updatedAt'>): Promise<Product>;
  delete(id: string): Promise<void>;
  bulk(operation: BulkOperation<Product>): Promise<BulkResult<Product>>;
}

// ============================================================
// Typed client
// ============================================================

export interface TypedDataNamespace {
  Product: TypedProductResource;
  Order: TypedOrderResource;
  Customer: TypedCustomerResource;
  // ... all entity types
}

export interface TypedOnePlatformClient extends Omit<OnePlatformClient, 'data'> {
  data: TypedDataNamespace;
}

export function createTypedClient(options: ClientOptions): TypedOnePlatformClient {
  const base = createClient(options);
  return {
    ...base,
    data: {
      Product: base.data.entity('Product') as TypedProductResource,
      Order: base.data.entity('Order') as TypedOrderResource,
      Customer: base.data.entity('Customer') as TypedCustomerResource,
      // ... all entity types
    },
  };
}

import { createTypedClient } from './oneplatform.gen';

const client = createTypedClient({
  baseUrl: 'https://platform.example.com',
  auth: { apiKey: process.env.OP_API_KEY },
});

// Fully typed: products is Product[]
const products = await client.data.Product.list({
  filter: (f) => f.status.eq('active').and(f.price.gt(100)),
  sort: '-createdAt',
}).collect(500);

// TypeScript enforces correct field names and value types
const order = await client.data.Order.create({
  customerId: 'cust_123',
  status: 'pending', // TypeScript: only 'pending' | 'fulfilled' | 'cancelled' allowed
  items: [],
  total: 0,
});

// Auth and identity
interface WhoAmIResponse {
  userId: string;
  email: string;
  tenantId: string;
  roles: string[];
  scopes: string[];
}

// Pipeline types
interface Pipeline {
  id: string;
  name: string;
  description: string | null;
  status: 'active' | 'paused' | 'draft';
  trigger: PipelineTrigger;
  createdAt: string;
  updatedAt: string;
}

interface PipelineRun {
  id: string;
  pipelineId: string;
  status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
  startedAt: string | null;
  completedAt: string | null;
  input: Record<string, unknown>;
  output: Record<string, unknown> | null;
  error: { message: string; code: string } | null;
}

// Connector types
interface ConnectorInstance {
  id: string;
  name: string;
  pluginId: string;
  status: 'healthy' | 'error' | 'unchecked';
  lastSyncAt: string | null;
  createdAt: string;
}

// Ontology types
interface OntologySchema {
  id: string;
  name: string;
  displayName: string;
  version: number;
  fields: OntologyField[];
  relationships: OntologyRelationship[];
  createdAt: string;
  updatedAt: string;
}

// API key types
interface ApiKey {
  id: string;
  name: string;
  prefix: string; // First 8 chars: "op_live_" prefix only, rest masked
  scopes: string[];
  createdAt: string;
  lastUsedAt: string | null;
  expiresAt: string | null;
}

interface CreatedApiKey extends ApiKey {
  /** Full key value. Returned exactly once. Store securely. */
  key: string;
}

// Log types
interface LogEntry {
  id: string;
  level: 'debug' | 'info' | 'warn' | 'error';
  message: string;
  service: string;
  traceId: string;
  tenantId: string;
  metadata: Record<string, unknown>;
  timestamp: string;
}

interface AuditEntry {
  id: string;
  action: string;
  actorId: string | null;
  actorType: 'user' | 'api-key' | 'service' | 'system';
  resourceType: string;
  resourceId: string;
  tenantId: string;
  metadata: Record<string, unknown>;
  traceId: string;
  timestamp: string;
}

// Bulk operation types
interface BulkOperation<T> {
  operation: 'create' | 'update' | 'delete';
  items: Array<Partial<T>>;
  transactional?: boolean;
}

interface BulkResult<T> {
  results: Array<
    | { index: number; id: string; status: 'success'; item: T }
    | { index: number; status: 'error'; error: { code: string; message: string } }
  >;
  summary: { total: number; succeeded: number; failed: number };
}