L2 Package Design: @oneplatform/plugin-sdk¶

// JSON Schema Draft 7 subset. Used for configSchema, outputSchema, inputSchema fields.
// Deliberately typed as Record<string, unknown> — full JSON Schema typing is out of scope
// for this SDK. Plugin authors use standard JSON Schema tooling (ajv, etc.) for authoring.
export type JSONSchema = Record<string, unknown>;

// A single record from an external data source, as produced by a Connector
// or consumed by a Transformer or Destination.
export interface DataRecord {
  // The record's stable identifier in the external system.
  // Used for deduplication and incremental sync (upsert by sourceId).
  sourceId: string;

  // The record's raw field values. Keys are arbitrary strings from the source.
  data: Record<string, unknown>;

  // Optional provenance metadata. Connectors should populate these when available.
  metadata?: {
    createdAt?: string;    // ISO 8601 from source system
    updatedAt?: string;    // ISO 8601 from source system
    deletedAt?: string;    // ISO 8601. Non-null signals a soft-delete event.
    checksum?: string;     // Content hash for change detection (e.g., MD5 of JSON)
  };
}

// A record that has been mapped to an ontology entity type.
// Produced by the Ontology Service after a raw DataRecord passes through mapping.
export interface MappedRecord {
  sourceId: string;
  entityType: string;            // Platform ontology entity type (e.g., "Customer")
  data: Record<string, unknown>; // Ontology-typed, validated field values
  operation: "upsert" | "delete";
}

export interface PluginContext {
  credentials: CredentialAccessor;
  fetch: FetchProxy;
  cache: CacheAccessor;
  logger: PluginLogger;
  tenant: TenantContext;
  ontology: OntologyAccessor;
  tracing: TracingContext;
}

export interface CredentialAccessor {
  /**
   * Returns the decrypted credential value for a named credential bound to this
   * plugin instance. Credentials are configured by a platform admin and bound
   * at enable time via the plugin instance configuration form.
   *
   * The returned string is the raw credential value (API key, token, password, etc.).
   * Never log this value. Never include it in error messages. Never store it in the
   * plugin's cache — the platform rotates credentials and will deliver updated values
   * automatically.
   *
   * @throws PluginAuthError if the credential is not found or decryption fails.
   */
  get(name: string): Promise<string>;

  /**
   * Returns the names of all credentials available to this plugin instance.
   * Use this to check for optional credentials before calling get().
   */
  list(): Promise<string[]>;
}

export interface FetchProxy {
  /**
   * Proxied HTTP fetch. Only URLs declared in manifest.requiredExternalUrls are
   * permitted. All internal OnePlatform service URLs are blocked unconditionally,
   * even if declared.
   *
   * URL matching is performed per-component on the parsed WHATWG URL:
   * - Protocol must match exactly (https:// required; http:// is blocked)
   * - Hostname must match exactly — no prefix/substring matching
   * - Path matching uses glob patterns on path segments only
   *
   * @throws PluginAuthError if the URL is not in the approved allowlist.
   */
  fetch(url: string, init?: RequestInit): Promise<Response>;
}

export interface CacheAccessor {
  /**
   * Get a value from the plugin instance's namespaced cache.
   * Cache keys are automatically scoped to {tenantId}:{instanceId} — two plugin
   * instances in the same tenant cannot read each other's cached data.
   *
   * Returns null if the key does not exist or has expired.
   */
  get<T>(key: string): Promise<T | null>;

  /**
   * Store a value in the plugin instance's namespaced cache.
   * @param ttlSeconds Optional TTL in seconds. If omitted, the value does not expire
   *                   until evicted by LRU pressure. Maximum TTL is 86400 (24 hours).
   */
  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;

  /**
   * Delete a key from the plugin instance's cache.
   * No-op if the key does not exist.
   */
  delete(key: string): Promise<void>;

  /**
   * Acquire a distributed mutex lock. Useful for ensuring only one execution at a
   * time performs a token refresh or other singleton operation.
   *
   * Returns a LockHandle if the lock was acquired, or null if it is already held.
   * Always call release() in a finally block.
   *
   * @param ttlSeconds Lock TTL. The lock is automatically released after this duration
   *                   even if release() is never called (prevents deadlocks).
   */
  lock(key: string, ttlSeconds: number): Promise<LockHandle | null>;
}

export interface LockHandle {
  release(): Promise<void>;
}

export interface PluginLogger {
  /**
   * Log a debug-level message. Debug logs are suppressed by default in production
   * tenants and are only visible with explicit debug mode enabled on the instance.
   */
  debug(message: string, metadata?: Record<string, unknown>): void;

  /** Log an informational message. Appears in the plugin execution log view. */
  info(message: string, metadata?: Record<string, unknown>): void;

  /**
   * Log a warning. Warnings are surfaced in the plugin monitoring dashboard and
   * increment the warning counter for this plugin instance.
   */
  warn(message: string, metadata?: Record<string, unknown>): void;

  /**
   * Log an error. Errors are surfaced in the plugin monitoring dashboard, increment
   * the error counter, and trigger alerting if configured by the tenant admin.
   *
   * IMPORTANT: Never pass credential values, access tokens, or PII in the metadata
   * argument. The metadata object is persisted to the platform logging system.
   */
  error(message: string, metadata?: Record<string, unknown>): void;
}

export interface TenantContext {
  /** UUID of the tenant that owns this plugin instance. */
  tenantId: string;

  /** Human-readable display name for this tenant. */
  tenantName: string;

  /**
   * Configuration values provided by the tenant admin at plugin enable time.
   * Values are validated against the plugin's manifest.configSchema before being
   * stored. Safe to read; always typed as Record<string, unknown>.
   */
  config: Record<string, unknown>;

  /**
   * Unique ID of this specific plugin instance within the tenant.
   * A single plugin can be enabled multiple times (e.g., two Shopify connectors
   * pointing to different stores). Each enable creates a distinct instanceId.
   */
  instanceId: string;
}

export interface OntologyAccessor {
  /**
   * Read-only access to the tenant's current ontology schema.
   * Returns all entity type definitions currently configured for this tenant.
   * Result is cached within a single execution — repeated calls do not make
   * additional network requests.
   *
   * Plugins CANNOT mutate the ontology. This method is read-only.
   */
  getSchema(): Promise<OntologySchema>;

  /**
   * Retrieve the schema for a single entity type by name.
   * Returns null if the entity type does not exist in this tenant's ontology.
   */
  getEntitySchema(entityType: string): Promise<EntitySchema | null>;
}

export interface OntologySchema {
  entityTypes: EntitySchema[];
  version: number;
  updatedAt: string; // ISO 8601
}

export interface EntitySchema {
  name: string;
  displayName: string;
  fields: EntityField[];
  primaryKey: string;
}

export interface EntityField {
  name: string;
  type: "string" | "number" | "boolean" | "date" | "datetime" | "json" | "reference";
  required: boolean;
  referenceTo?: string; // Entity type name, if type === "reference"
}

export interface TracingContext {
  /**
   * Inject the current trace context into an outbound request headers object.
   * Use this with FetchProxy to propagate distributed traces into external service
   * calls. The returned object is a new object containing the original headers
   * plus the injected trace headers (W3C traceparent/tracestate).
   *
   * Example:
   *   const headers = ctx.tracing.injectHeaders({ "Content-Type": "application/json" });
   *   const response = await ctx.fetch(url, { headers });
   */
  injectHeaders(headers: Record<string, string>): Record<string, string>;

  /**
   * Create a child span for a named operation. The span is automatically parented
   * to the current execution trace. Call setAttribute() to add context, and always
   * call end() in a finally block.
   *
   * Example:
   *   const span = ctx.tracing.startSpan("fetchOrders");
   *   try {
   *     // ... do work ...
   *     span.setAttribute("order.count", records.length);
   *   } finally {
   *     span.end();
   *   }
   */
  startSpan(name: string): SpanHandle;
}

export interface SpanHandle {
  setAttribute(key: string, value: string | number | boolean): void;
  end(): void;
}

export interface ConnectorHandle {
  /**
   * Opaque identifier for this active connection, assigned by the plugin.
   * Used to correlate fetchBatch and disconnect calls to the same connection.
   * Must be a string. The platform stores this between fetchBatch calls to
   * support resumable ingestion.
   */
  connectionId: string;

  /**
   * Plugin-managed connection state. May include auth tokens, base URLs,
   * or other values needed by fetchBatch and disconnect.
   * Must be JSON-serializable (the platform may checkpoint this between calls).
   */
  metadata: Record<string, unknown>;
}

export interface BatchResult {
  records: DataRecord[];

  /**
   * Cursor for the next fetchBatch call. Set to null to signal that all records
   * have been returned. The cursor value is opaque to the platform — it may be
   * a page token, timestamp, offset, or any string the connector uses internally.
   */
  nextCursor: string | null;

  /** Set to true if there are more records after this batch (i.e., nextCursor is non-null). */
  hasMore: boolean;

  /** ISO 8601 timestamp of when this batch was fetched. Used for freshness tracking. */
  fetchedAt: string;

  /**
   * Advisory hint for the platform progress UI. If unknown, omit this field.
   * The platform never makes correctness decisions based on this value.
   */
  estimatedTotal?: number;
}

export interface EventCallback {
  (event: DataRecord): Promise<void>;
}

export interface Subscription {
  unsubscribe(): Promise<void>;
  isActive(): boolean;
}

export interface Connector {
  /**
   * Return the connector's metadata. Called by the Plugin Service at install time
   * to verify the entrypoint is valid, and by the Ingestion Service to display
   * connector details in the data source catalog.
   */
  metadata(): ConnectorMetadata;

  /**
   * Validate the plugin configuration and credentials, and establish a connection.
   * Called once per ingestion job before the first fetchBatch call.
   *
   * This method should be fast (< 5 seconds). If the external service requires
   * a round-trip for auth (e.g., OAuth token refresh), do it here and cache the
   * token in the context.cache.
   *
   * @throws PluginConfigError if config is invalid or missing required fields.
   * @throws PluginAuthError if credential validation fails.
   */
  connect(
    config: Record<string, unknown>,
    context: PluginContext
  ): Promise<ConnectorHandle>;

  /**
   * Fetch the next batch of records from the external system.
   *
   * cursor=undefined signals the first call (fetch from the beginning of available data).
   * For incremental syncs, the cursor is the value returned by the previous fetchBatch.
   * The platform stores the last successful cursor and resumes from it on retry.
   *
   * Batch size should be controlled by the connector, typically 100-1000 records.
   * Avoid batches larger than 10,000 records — the platform's ingestion queue has
   * per-message limits.
   *
   * @throws PluginRateLimitError if the external API returns 429.
   * @throws PluginTimeoutError if a network call exceeds the configured timeout.
   * @throws PluginAuthError if the connection credentials have expired.
   */
  fetchBatch(
    handle: ConnectorHandle,
    cursor: string | undefined,
    context: PluginContext
  ): Promise<BatchResult>;

  /**
   * Subscribe to real-time change events from the external system.
   * Only implement if ConnectorMetadata.supportsRealtime is true.
   *
   * The platform calls this method once when a real-time data source is activated.
   * The callback receives individual change events as they arrive. Each callback
   * invocation is an async operation — the connector must await it before processing
   * the next event to maintain ordering.
   *
   * The returned Subscription must remain active until unsubscribe() is called,
   * which happens when the tenant disables real-time on the data source.
   */
  subscribeToEvents?(
    handle: ConnectorHandle,
    callback: EventCallback,
    context: PluginContext
  ): Promise<Subscription>;

  /**
   * Clean up the connection. Called after the ingestion job completes or on error.
   * Must not throw. If cleanup fails, log the error and return.
   *
   * Resources to release: HTTP connections, open file handles, WebSocket connections.
   * Do NOT revoke OAuth tokens here — they may be reused by the next ingestion run.
   */
  disconnect(handle: ConnectorHandle, context: PluginContext): Promise<void>;
}

export interface TransformerContext {
  tenant: TenantContext;
  logger: PluginLogger;
  ontology: OntologyAccessor;
  cache: CacheAccessor;
  tracing: TracingContext;

  /**
   * Present when the transformer runs inside a named pipeline run.
   * Use for logging and correlation, not for control flow.
   */
  pipelineRunId?: string;

  /** The ID of the pipeline step that invoked this transformer. */
  stageId?: string;
}

export interface Transformer {
  metadata(): TransformerMetadata;

  /**
   * Transform a single record.
   *
   * Return the (possibly modified) DataRecord to pass it downstream.
   * Return null to drop the record — it will not appear in the output.
   * Do not mutate the input record — return a new object.
   *
   * @throws PluginDataError if the record is malformed and cannot be processed.
   *         The platform will route the record to the pipeline's dead-letter queue.
   *         Do not throw for recoverable data issues — return a modified record instead.
   */
  transform(
    record: DataRecord,
    context: TransformerContext
  ): Promise<DataRecord | null>;

  /**
   * Transform a batch of records. Optional optimization for transformers that can
   * process records more efficiently in bulk (e.g., batch enrichment API calls).
   *
   * If implemented, the platform uses this instead of calling transform() N times.
   * The result array must preserve ordering: records[i] maps to result[i] or is
   * absent (dropped). Use an empty array to drop all records.
   *
   * The platform NEVER calls both transform() and transformBatch() for the same
   * batch — it prefers transformBatch() if present.
   */
  transformBatch?(
    records: DataRecord[],
    context: TransformerContext
  ): Promise<DataRecord[]>;
}

export interface WriteResult {
  /** Count of records successfully written. */
  written: number;

  /** Count of records that failed. */
  failed: number;

  /**
   * Per-record error details for failed records.
   * Include the sourceId so the platform can correlate failures to records.
   * Do not include credential values in the error string.
   */
  errors: Array<{ sourceId: string; error: string }>;
}

export interface DestinationContext {
  tenant: TenantContext;
  logger: PluginLogger;
  cache: CacheAccessor;
  fetch: FetchProxy;
  tracing: TracingContext;
}

export interface Destination {
  metadata(): DestinationMetadata;

  /**
   * Write a batch of mapped records to the destination.
   *
   * The platform calls this with batches sized according to the destination's
   * delivery guarantee. For at-least-once destinations, the same record may be
   * delivered more than once (e.g., after a retry). The destination must handle
   * idempotent writes if its DestinationMetadata.deliveryGuarantee is
   * "at-least-once" or "exactly-once".
   *
   * Never partially fail silently — report all failures in WriteResult.errors.
   * The platform uses this to trigger DLQ routing.
   */
  write(
    records: MappedRecord[],
    context: DestinationContext
  ): Promise<WriteResult>;

  /**
   * Stream records to the destination. Only implement if
   * DestinationMetadata.supportsStreaming is true.
   *
   * The platform provides an AsyncIterable of records. The destination should
   * maintain an open connection to the target system and write records as they
   * arrive. Return a WriteResult when the stream is exhausted.
   */
  writeStream?(
    stream: AsyncIterable<MappedRecord>,
    context: DestinationContext
  ): Promise<WriteResult>;
}

export interface AuthOptions {
  /** The platform's OAuth callback URL. Must be included verbatim in the authorization URL. */
  redirectUri: string;

  /** OAuth scopes to request. If omitted, the provider's default scopes apply. */
  scopes?: string[];

  /** Provider-specific query parameters to append to the authorization URL. */
  additionalParams?: Record<string, string>;
}

export interface CallbackParams {
  /**
   * The authorization code from the OAuth provider.
   * For SAML flows, this is the decoded assertion value after base64 decoding.
   */
  code: string;

  /** Set if the provider returned an error in the callback. */
  error?: string;

  /** Human-readable description of the error, if present. */
  errorDescription?: string;
}

export interface AuthContext {
  tenant: TenantContext;
  logger: PluginLogger;

  /**
   * Cache accessor for storing PKCE code verifiers, nonces, or other
   * short-lived values needed across the two legs of the auth flow.
   * Use TTLs of 300 seconds (5 minutes) for these values.
   */
  cache: CacheAccessor;
}

export interface AuthResult {
  accessToken: string;
  refreshToken?: string;

  /** ISO 8601 expiry time for the access token. */
  expiresAt?: string;

  /** Raw claims from the identity provider. Used by mapClaimsToRoles(). */
  claims: Record<string, unknown>;

  /** Platform RBAC role names assigned to this user, as returned by mapClaimsToRoles(). */
  platformRoles: string[];

  /** The user's stable ID in the external identity provider. */
  providerUserId: string;
}

export interface TokenValidation {
  valid: boolean;
  claims?: Record<string, unknown>;
  expiresAt?: string;
  error?: string;
}

export interface TokenPair {
  accessToken: string;
  refreshToken?: string;
  expiresAt?: string;
}

export interface AuthProvider {
  metadata(): AuthProviderMetadata;

  /**
   * Build the authorization URL that the browser navigates to.
   * This method is synchronous — it should not make network calls.
   *
   * @param state An opaque, cryptographically random string generated by the Auth Service.
   *              Include this in the authorization URL as the `state` query parameter.
   *              The Auth Service will verify it matches when the callback arrives.
   * @param options Platform-provided callback configuration.
   * @returns The full authorization URL to redirect the browser to.
   */
  getAuthorizationUrl(state: string, options: AuthOptions): string;

  /**
   * Handle the OAuth callback. Exchange the authorization code for tokens.
   *
   * The Auth Service has already verified the state parameter (CSRF check) before
   * calling this method. The plugin should exchange the code for tokens and return
   * an AuthResult. Never call external token validation URLs from this method —
   * the platform considers the tokens valid if they arrive in the provider's callback.
   *
   * @throws PluginAuthError if the code exchange fails (e.g., expired code, bad credentials).
   */
  handleCallback(
    params: CallbackParams,
    context: AuthContext
  ): Promise<AuthResult>;

  /**
   * Validate an access token with the external provider.
   * Only implement if AuthProviderMetadata.supportsTokenValidation is true.
   * Called on API requests to verify the token has not been revoked externally.
   *
   * @returns TokenValidation with valid=false if the token is expired or revoked.
   *          Do not throw for invalid tokens — return valid=false.
   * @throws PluginAuthError only for unrecoverable errors (e.g., provider unreachable).
   */
  validateToken?(
    token: string,
    context: AuthContext
  ): Promise<TokenValidation>;

  /**
   * Exchange a refresh token for a new access token.
   * Only implement if AuthProviderMetadata.supportsTokenRefresh is true.
   *
   * Use context.cache.lock() to prevent concurrent refreshes for the same user.
   *
   * @throws PluginAuthError if the refresh token is expired or revoked.
   */
  refreshToken?(
    refreshToken: string,
    context: AuthContext
  ): Promise<TokenPair>;

  /**
   * Map external identity provider claims to OnePlatform RBAC role names.
   * Called during login and on every token refresh to keep role assignments current.
   *
   * Returns an array of platform role name strings. Roles that do not exist in
   * the platform are ignored. An empty array means the user has no roles (they
   * can still log in but will have no permissions).
   *
   * This method is synchronous and must not make network calls.
   */
  mapClaimsToRoles(claims: Record<string, unknown>): string[];
}

export type WidgetSlot = "main" | "sidebar" | "header" | "footer" | "fullscreen";

export interface WidgetSlotDeclaration {
  slot: WidgetSlot;
  defaultWidth: number;  // Grid units (1-12)
  defaultHeight: number; // Grid units (1-12)
}

export interface DataQuery {
  entityType: string;
  filter?: Record<string, unknown>;
  sort?: string;
  fields?: string[];
  limit?: number;
}

export interface WidgetData {
  /**
   * Pre-fetched query results, keyed by entityType.
   * Populated by the platform before render() is called.
   * The platform fetches data using the tenant's access rights — widgets
   * never make data API calls directly.
   */
  queryResults: Record<string, unknown[]>;

  /** The widget instance's configuration values. */
  config: Record<string, unknown>;

  /** The requesting user's identity and roles. Use for conditional rendering only. */
  user: { id: string; roles: string[] };
}

export interface Widget {
  metadata(): WidgetMetadata;

  /**
   * Return a complete HTML document string to be served inside the widget iframe.
   *
   * Security constraints:
   * - Do not include <script> tags in the output. DOMPurify (server-side) strips
   *   all <script> elements. The platform injects a bootstrap script via nonce.
   * - Do not attempt to access window.parent or window.top — the iframe uses
   *   sandbox="allow-scripts" (no allow-same-origin), creating an opaque origin.
   * - Use inline styles freely (style-src 'unsafe-inline' is permitted).
   * - Do not embed external images — use data URIs or serve from the widget bundle.
   *
   * The returned HTML must be a complete document (<html><head><body>...</body></html>).
   */
  render(data: WidgetData): string;

  /**
   * Declare what platform data this widget needs.
   * The platform pre-fetches this data before calling render(), so render() receives
   * fully populated WidgetData.queryResults without making any async calls.
   *
   * Keep queries minimal — each declared query adds latency to the dashboard load.
   */
  declareDataRequirements(): DataQuery[];

  /** Declare which slot(s) this widget can render in. */
  declareSlot(): WidgetSlotDeclaration;
}

/**
 * Base class for all plugin errors. Do not throw PluginError directly —
 * use one of the typed subclasses below.
 */
export class PluginError extends Error {
  constructor(
    message: string,
    /** Machine-readable error code, e.g., "INVALID_CURSOR". Snake_case, uppercase. */
    public readonly code: string,
    /**
     * Whether the Execution Service should retry this execution.
     * true:  transient failure, retry with backoff (rate limits, timeouts, 5xx)
     * false: permanent failure, route to DLQ immediately (bad config, bad data)
     */
    public readonly isRetryable: boolean,
    /** Structured context for debugging. Never include credential values. */
    public readonly details?: Record<string, unknown>
  ) {
    super(message);
    this.name = this.constructor.name;
    // Maintain correct prototype chain when transpiled to ES5 or CommonJS
    Object.setPrototypeOf(this, new.target.prototype);
  }
}

/**
 * The external service returned 401 or 403.
 * isRetryable=false: credential rotation (a human action) is required before retry.
 * The platform surfaces this error in the plugin monitoring dashboard immediately.
 */
export class PluginAuthError extends PluginError {
  constructor(message: string, details?: Record<string, unknown>) {
    super(message, "PLUGIN_AUTH_ERROR", false, details);
  }
}

/**
 * The external service returned 429 (Too Many Requests).
 * isRetryable=true: the Execution Service respects retryAfterSeconds if present,
 * otherwise applies exponential backoff (base 2s, max 300s, jitter ±20%).
 */
export class PluginRateLimitError extends PluginError {
  constructor(
    message: string,
    /** Hint from the external service's Retry-After header, if present. */
    public readonly retryAfterSeconds?: number
  ) {
    super(message, "PLUGIN_RATE_LIMIT", true, { retryAfterSeconds });
  }
}

/**
 * A network call timed out, or the execution sandbox timeout was reached.
 * isRetryable=true: timeouts are often transient.
 * The platform logs the timeout duration alongside this error for diagnosis.
 */
export class PluginTimeoutError extends PluginError {
  constructor(message: string) {
    super(message, "PLUGIN_TIMEOUT", true);
  }
}

/**
 * The external service returned malformed, unexpected, or unprocessable data.
 * isRetryable=false: the data shape is wrong; retrying will produce the same error.
 * The platform routes the record to the DLQ with the sample attached.
 *
 * Include a sample of the problematic data in the sample parameter for DLQ debugging.
 * Truncate large samples to 1KB.
 */
export class PluginDataError extends PluginError {
  constructor(
    message: string,
    /** A sample of the data that could not be processed. Truncate to 1KB. */
    public readonly sample?: unknown
  ) {
    super(message, "PLUGIN_DATA_ERROR", false, { sample });
  }
}

/**
 * A required configuration field is missing or has an invalid value.
 * isRetryable=false: configuration is static; retrying without configuration
 * change will produce the same error.
 *
 * Throw this from connect() when a required config field is absent or invalid.
 * Do not throw this from fetchBatch — configuration issues should be caught at
 * connect() time.
 */
export class PluginConfigError extends PluginError {
  constructor(
    message: string,
    /** The name of the config field that is missing or invalid. */
    public readonly field?: string
  ) {
    super(message, "PLUGIN_CONFIG_ERROR", false, { field });
  }
}

export interface BaseMetadata {
  /** Must match manifest.id exactly. */
  id: string;

  /** Human-readable display name. 2-100 characters. */
  name: string;

  /** Brief description shown in the marketplace. 10-500 characters. */
  description: string;

  /** Must match manifest.version exactly. */
  version: string;

  /** Plugin author name or organization. */
  author: string;

  /** URL or data URI for the plugin icon. PNG or SVG, max 64KB. */
  icon?: string;

  /** JSON Schema for the tenant-admin configuration form. */
  configSchema: JSONSchema;

  /** Discoverability tags shown in the marketplace filter UI. */
  tags?: string[];
}

export interface ConnectorMetadata extends BaseMetadata {
  readonly type: "connector";

  /**
   * Marketplace category. Standard values: "crm", "ecommerce", "database",
   * "file", "analytics", "marketing", "finance", "devtools", "iot", "other".
   */
  category: string;

  /** JSON Schema describing the shape of records this connector produces. */
  outputSchema: JSONSchema;

  /** True if the connector supports cursor-based incremental fetching. */
  supportsIncremental: boolean;

  /** True if the connector implements subscribeToEvents(). */
  supportsRealtime: boolean;

  /**
   * Advisory rate limit hint for the Ingestion Service's scheduling algorithm.
   * Does not enforce anything — the connector is responsible for enforcing its own
   * rate limits by throwing PluginRateLimitError.
   */
  rateLimit?: {
    requestsPerMinute: number;
    rowsPerSecond?: number;
  };
}

export interface TransformerMetadata extends BaseMetadata {
  readonly type: "transformer";

  /** JSON Schema for accepted record shape. null means any shape is accepted. */
  inputSchema?: JSONSchema;

  /** JSON Schema for output record shape. null means shape mirrors input. */
  outputSchema?: JSONSchema;

  /**
   * True if transform(transform(x)) === transform(x) for all x.
   * Idempotent transformers can be safely retried without data duplication.
   */
  idempotent: boolean;
}

export interface DestinationMetadata extends BaseMetadata {
  readonly type: "destination";

  /** JSON Schema for the record shape this destination accepts. null = any shape. */
  acceptedSchema?: JSONSchema;

  /**
   * Delivery guarantee provided by this destination's write() implementation.
   * "at-most-once":  records may be lost on failure; no retry
   * "at-least-once": records are retried on failure; destination must handle duplicates
   * "exactly-once":  records are deduplicated by sourceId; strongest guarantee
   */
  deliveryGuarantee: "at-most-once" | "at-least-once" | "exactly-once";

  /** True if the destination supports write() with batches > 1. */
  supportsBulk: boolean;

  /** True if the destination implements writeStream(). */
  supportsStreaming: boolean;
}

export interface AuthProviderMetadata extends BaseMetadata {
  readonly type: "auth-provider";

  /** The identity protocol this provider implements. */
  protocol: "oauth2" | "saml" | "oidc" | "ldap" | "custom";

  /** True if the provider implements validateToken(). */
  supportsTokenValidation: boolean;

  /** True if the provider implements refreshToken(). */
  supportsTokenRefresh: boolean;

  /**
   * OAuth scopes this provider supports. Shown in the admin configuration UI.
   * Omit for non-OAuth providers.
   */
  scopes?: string[];
}

export interface WidgetMetadata extends BaseMetadata {
  readonly type: "widget";

  /** Minimum grid width. Integer 1-12. */
  minWidth: number;

  /** Minimum grid height. Integer 1-12. */
  minHeight: number;

  /** Maximum grid width. Omit for no constraint. */
  maxWidth?: number;

  /** Maximum grid height. Omit for no constraint. */
  maxHeight?: number;

  /** Slots this widget can render in. */
  slots: WidgetSlotDeclaration[];
}

/** Union of all metadata types for use in generic plugin-handling code. */
export type AnyPluginMetadata =
  | ConnectorMetadata
  | TransformerMetadata
  | DestinationMetadata
  | AuthProviderMetadata
  | WidgetMetadata;

/**
 * All valid hook stages. The pattern is "{timing}:{domain}.{event}" or
 * "{timing}:{domain}.{event}:{stepId}" for parameterized pipeline step hooks.
 *
 * Timing: "before" = before the stage executes; "after" = after the stage executes.
 */
export type HookStage =
  // Ingestion Service
  | "before:ingestion.receive"
  | "after:ingestion.receive"
  | "before:ingestion.validate"
  | "after:ingestion.validate"
  | "before:ingestion.enrich"
  | "after:ingestion.enrich"
  | "before:ingestion.stage"
  | "after:ingestion.stage"
  // Ontology Service
  | "before:ontology.map"
  | "after:ontology.map"
  | "before:ontology.normalize"
  | "after:ontology.normalize"
  // Pipeline Service
  | "before:pipeline.trigger"
  | "after:pipeline.trigger"
  | "before:pipeline.step"
  | "after:pipeline.step"
  | "before:pipeline.complete"
  | "after:pipeline.complete"
  // Execution Service
  | "before:execution.before"
  | "after:execution.before"
  | "before:execution.after"
  | "after:execution.after"
  // Auth Service
  | "before:auth.login"
  | "after:auth.login"
  | "after:auth.logout"
  | "before:auth.token.issue"
  | "after:auth.token.issue"
  // App Service
  | "before:app.request"
  | "after:app.request"
  | "before:app.build"
  | "after:app.build"
  // Parameterized pipeline step (stepId substituted at registration time)
  | `before:pipeline.step:${string}`
  | `after:pipeline.step:${string}`;

export interface HookDeclaration {
  /**
   * The hook stage this declaration registers for.
   * Must be one of the HookStage values above.
   */
  stage: HookStage;

  /**
   * Criticality determines what happens when this hook fails or times out.
   *
   * "critical":  Hook failure aborts the stage and returns an error to the caller.
   *              Use for hooks that enforce invariants (e.g., schema validation).
   * "advisory":  Hook failure is logged but the stage continues with the pre-hook
   *              payload. Use for enrichment or observability hooks.
   */
  criticality: "critical" | "advisory";

  /**
   * Execution order within a stage's hook chain. Lower priority = earlier execution.
   * Default: 100. Valid range: 0-999.
   * When two hooks share the same priority, execution order is deterministic but
   * not specified — do not rely on ordering between plugins with equal priority.
   */
  priority?: number;

  /**
   * Execution timeout override for this specific hook.
   * Default: 30 seconds. Maximum: 300 seconds.
   * Must be specified in seconds as a positive integer.
   */
  timeout?: number;

  /**
   * The named export in dist/bundle.js that implements this hook.
   * Example: "onBeforeIngestionReceive"
   *
   * The export must be a function with this signature:
   *   async function onBeforeIngestionReceive(
   *     payload: HookPayload,
   *     context: PluginContext
   *   ): Promise<HookResult>
   */
  entrypoint: string;
}

/**
 * The payload passed to every hook function.
 * The concrete shape of `data` depends on the hook stage.
 * Hook functions may return a modified payload to alter platform behavior.
 */
export interface HookPayload {
  /** The stage that triggered this hook. */
  stage: HookStage;

  /** The data being processed at this stage. Shape varies by stage. */
  data: Record<string, unknown>;

  /** Metadata about the execution context. */
  context: {
    tenantId: string;
    traceId: string;
    spanId: string;
    pipelineRunId?: string;
    ingestionJobId?: string;
  };
}

/**
 * The return type of a hook function.
 * To modify the data flowing through the stage, return a new payload.
 * To pass data through unmodified, return the input payload unchanged.
 * Returning null from an advisory hook is equivalent to returning the input payload.
 */
export interface HookResult {
  /** The (possibly modified) data to pass to the next hook or to the stage itself. */
  data: Record<string, unknown>;
}

import { z } from "zod";

const JSONSchemaZ = z.record(z.unknown());

const HookDeclarationZ = z.object({
  stage: z.string().min(1),
  criticality: z.enum(["critical", "advisory"]),
  priority: z.number().int().min(0).max(999).optional(),
  timeout: z.number().int().min(1).max(300).optional(),
  entrypoint: z.string().regex(/^[a-zA-Z_$][a-zA-Z0-9_$]*$/, {
    message: "entrypoint must be a valid JavaScript identifier",
  }),
});

const RequiredCredentialZ = z.object({
  name: z.string().min(1).max(100),
  description: z.string().min(1).max(500),
  type: z.enum(["secret", "password", "token", "certificate"]),
  required: z.boolean(),
});

export const PluginManifestSchema = z.object({
  manifestVersion: z.literal("1"),

  id: z
    .string()
    .min(3)
    .max(200)
    .regex(/^[a-z0-9]+(\.[a-z0-9][a-z0-9-]*[a-z0-9])+$/, {
      message:
        "id must be reverse-domain format, e.g. com.example.my-plugin",
    }),

  name: z.string().min(2).max(100),

  version: z
    .string()
    .regex(/^\d+\.\d+\.\d+(-[a-zA-Z0-9.+-]+)?(\+[a-zA-Z0-9.+]+)?$/, {
      message: "version must be SemVer, e.g. 1.2.3 or 1.0.0-beta.1",
    }),

  type: z.enum([
    "connector",
    "transformer",
    "destination",
    "auth-provider",
    "widget",
  ]),

  description: z.string().min(10).max(200),

  author: z.string().min(1).max(200),

  supportUrl: z.string().url().optional(),
  homepageUrl: z.string().url().optional(),

  icon: z
    .string()
    .refine(
      (v) =>
        v.startsWith("https://") ||
        v.startsWith("data:image/png;base64,") ||
        v.startsWith("data:image/svg+xml;base64,"),
      { message: "icon must be an https URL or a PNG/SVG data URI" }
    )
    .optional(),

  minPlatformVersion: z
    .string()
    .regex(/^\d+\.\d+\.\d+$/, {
      message: "minPlatformVersion must be a simple x.y.z SemVer",
    }),

  entrypoint: z.string().regex(/^[a-zA-Z_$][a-zA-Z0-9_$]*$/, {
    message: "entrypoint must be a valid JavaScript identifier",
  }),

  configSchema: JSONSchemaZ,

  hooks: z.array(HookDeclarationZ).default([]),

  requiredExternalUrls: z
    .array(
      z.string().refine(
        (u) => u.startsWith("https://"),
        { message: "requiredExternalUrls entries must use https://" }
      )
    )
    .default([]),

  requiredApis: z
    .array(
      z.enum(["credentials", "fetch", "cache", "ontology", "tracing"])
    )
    .default([]),

  requiredCredentials: z.array(RequiredCredentialZ).default([]),

  bundleChecksum: z
    .string()
    .regex(/^[a-f0-9]{64}$/, {
      message: "bundleChecksum must be a 64-character lowercase hex SHA-256",
    }),

  gpgFingerprint: z
    .string()
    .regex(/^[A-F0-9]{40}$/, {
      message: "gpgFingerprint must be a 40-character uppercase hex fingerprint",
    })
    .optional(),

  tags: z.array(z.string().min(1).max(50)).max(20).optional(),

  license: z
    .string()
    .min(1)
    .max(50)
    .regex(/^[A-Za-z0-9\-.+]+$/, {
      message: "license must be an SPDX identifier, e.g. MIT or Apache-2.0",
    }),

  changelog: z.string().max(5000).optional(),
});

export type PluginManifest = z.infer<typeof PluginManifestSchema>;

// On validation failure, the CLI and Plugin Service both produce this structure:
interface ManifestValidationError {
  valid: false;
  errors: Array<{
    path: string;        // Dot-separated path, e.g., "hooks[0].entrypoint"
    message: string;     // Human-readable validation message
    received?: unknown;  // The value that failed validation (omitted for security)
  }>;
}

import type {
  Connector,
  ConnectorHandle,
  ConnectorMetadata,
  BatchResult,
  PluginContext,
} from "@oneplatform/plugin-sdk";
import { PluginAuthError, PluginConfigError, PluginRateLimitError } from "@oneplatform/plugin-sdk";

export const SalesforceConnector: Connector = {
  metadata(): ConnectorMetadata {
    return {
      type: "connector",
      id: "com.acme.salesforce-connector",
      name: "Salesforce Connector",
      description: "Connects OnePlatform to Salesforce CRM",
      version: "0.1.0",
      author: "Acme Corp",
      category: "crm",
      configSchema: {
        type: "object",
        required: ["instanceUrl"],
        properties: {
          instanceUrl: { type: "string" },
        },
      },
      outputSchema: {
        type: "object",
        properties: {
          Id: { type: "string" },
          Name: { type: "string" },
        },
      },
      supportsIncremental: true,
      supportsRealtime: false,
    };
  },

  async connect(
    config: Record<string, unknown>,
    context: PluginContext
  ): Promise<ConnectorHandle> {
    const instanceUrl = config["instanceUrl"];
    if (typeof instanceUrl !== "string" || !instanceUrl) {
      throw new PluginConfigError("instanceUrl is required", "instanceUrl");
    }

    const clientId = await context.credentials.get("clientId");
    const clientSecret = await context.credentials.get("clientSecret");

    // TODO: Implement OAuth2 token acquisition
    // const token = await acquireToken(instanceUrl, clientId, clientSecret, context);

    return {
      connectionId: `sf-${Date.now()}`,
      metadata: { instanceUrl, accessToken: "TODO" },
    };
  },

  async fetchBatch(
    handle: ConnectorHandle,
    cursor: string | undefined,
    context: PluginContext
  ): Promise<BatchResult> {
    const offset = cursor ? parseInt(cursor, 10) : 0;
    context.logger.info("Fetching batch", { offset });

    // TODO: Implement actual API call
    // const result = await context.fetch(
    //   `${handle.metadata.instanceUrl}/services/data/v60.0/query?q=...OFFSET ${offset}`,
    //   { headers: { Authorization: `Bearer ${handle.metadata.accessToken}` } }
    // );

    return {
      records: [],
      nextCursor: null,
      hasMore: false,
      fetchedAt: new Date().toISOString(),
    };
  },

  async disconnect(
    handle: ConnectorHandle,
    context: PluginContext
  ): Promise<void> {
    context.logger.info("Disconnecting", { connectionId: handle.connectionId });
  },
};