@kindgi/sdk 0.0.0-bootstrap.0 → 0.1.1

package/src/client.ts

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk/client` — client callsite surface.
+ *
+ * Re-exports `createClient` plus every resource-client type, the error
+ * surface, transport primitives, and streaming helpers from the
+ * `@kindgi/client` package (`sdks/typescript/` in this repository).
+ * Names preserved verbatim.
+ *
+ * This sub-path intentionally does NOT re-export the branded ID types
+ * (`AgentId`, `RunId`, etc.) that `@kindgi/client` also happens to
+ * surface — those live in `@kindgi/sdk/types` to keep the flat barrel
+ * (`import { ... } from '@kindgi/sdk'`) collision-free.
+ *
+ * Callsite examples target
+ * `import { createClient } from '@kindgi/sdk/client'`.
+ *
+ * @module @kindgi/sdk/client
+ */
+
+// ---- Client factory + top-level shape ----
+import { createClient as createKindgiClient } from '@kindgi/client';
+import type { ClientOptions, KindgiClient } from '@kindgi/client';
+
+import { resolveClientOptions } from './runtime-config.js';
+
+export type { KindgiClient } from '@kindgi/client';
+
+/**
+ * A client for the app's Kindgi runtime. Every option is optional:
+ *
+ * - `apiUrl` and `auth` come from `KINDGI_API_URL` and `KINDGI_API_TOKEN`;
+ * - outside production, when those aren't set, from the running
+ *   `kindgi dev` (the nearest `.kindgirc.json`), with a one-time warning to
+ *   put them in the app's env file;
+ * - a token that doesn't match the running `kindgi dev`'s for the same
+ *   `apiUrl` (after `kindgi dev --reset`) is warned about once.
+ *
+ * Production (`NODE_ENV` or `KINDGI_ENV` = `production`) never reads
+ * `.kindgirc.json`: there, the env or explicit options must say. In a
+ * browser, pass `apiUrl` and `auth`. `@kindgi/client`'s `createClient` is
+ * the explicit form underneath.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@kindgi/sdk/client';
+ *
+ * const kindgi = createClient();
+ * ```
+ */
+export function createClient(options: Partial<ClientOptions> = {}): KindgiClient {
+  return createKindgiClient(resolveClientOptions(options));
+}
+
+// ---- Resource client types + per-resource input shapes ----
+export type {
+  AdapterConfigureInput,
+  AdapterFilter,
+  AdapterTestInput,
+  AdaptersClient,
+  AddMembershipInput,
+  AgentsClient,
+  ApplyProposalInput,
+  ApprovalFilter,
+  ApprovalsClient,
+  ArtifactFilter,
+  ArtifactsClient,
+  AuditClient,
+  AuditExportInput,
+  BatchDecideInput,
+  BudgetsClient,
+  CapabilitiesClient,
+  CapabilityFilter,
+  ClientOptions,
+  CompleteTokenInput,
+  ConversationFilter,
+  ConversationsClient,
+  CostClient,
+  DecideInput,
+  DraftProposalsInput,
+  EventsClient,
+  FactsClient,
+  FlowFilter,
+  FlowsClient,
+  FlowValidateResult,
+  GuardrailFilter,
+  GuardrailsClient,
+  LogsClient,
+  McpClient,
+  McpEndpointFilter,
+  McpEndpointsClient,
+  TeamMembershipsClient,
+  MemoryClient,
+  MessageFilter,
+  ObservationFilter,
+  ObservationsClient,
+  OrgsClient,
+  PackFilter,
+  PacksClient,
+  PageFilter,
+  PatternsInput,
+  PoliciesClient,
+  PolicyListFilter,
+  PolicyVersionsFilter,
+  ProposalDryRunInput,
+  ProposalListInput,
+  ProposalsClient,
+  ProvenanceClient,
+  ProvenanceExportInput,
+  ProviderFilter,
+  ProvidersClient,
+  ReflectReviewInput,
+  RegistryClient,
+  RegistryFilter,
+  ResumeRunInput,
+  ReviewerFilter,
+  ReviewersClient,
+  RollbackProposalInput,
+  Run,
+  RunsClient,
+  SchedulesClient,
+  SessionsClient,
+  StartRunInput,
+  SubmitForReviewInput,
+  SubscriptionsClient,
+  SupervisorClient,
+  ListTeamsFilter,
+  TeamsClient,
+  TenantClient,
+  TenantConfigClient,
+  TokenFilter,
+  TokensClient,
+  ReinstateToolVersionResult,
+  ToolFilter,
+  ToolVersionFilter,
+  ToolsClient,
+  Transport,
+  TransportRequest,
+  UsageClient,
+  UsageSummaryInput,
+  UserFilter,
+  UsersClient,
+  WebhooksClient,
+  WithdrawProposalInput,
+} from '@kindgi/client';
+
+// ---- Error surface ----
+export { KindgiApiError, fromWire, notImplementedInPreview, notYetWired } from '@kindgi/client';
+export type {
+  AuthError,
+  ConflictError,
+  GuardrailViolation,
+  GuardrailViolationError,
+  InvalidRequestError,
+  NetworkError,
+  NotFoundError,
+  NotImplementedInPreviewError,
+  NotYetWiredError,
+  RateLimitedError,
+  ServerError,
+  KindgiError,
+} from '@kindgi/client';
+
+// ---- Streaming helpers (SSE parser + resume) ----
+export { readSse, unwrapSseData } from '@kindgi/client';
+export type { SseEvent, SseReadOptions } from '@kindgi/client';
+
+// ---- Following a run (browser-safe: a page follows a run with a public token) ----
+export { followRun, subscribeToRun } from '@kindgi/client';
+export type {
+  FollowRunOptions,
+  RunProgress,
+  RunProgressEvent,
+  SubscribeToRunOptions,
+} from '@kindgi/client';

package/src/define.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk/define` — pack authoring surface.
+ *
+ * Re-exports the authoring primitives from the individual packages
+ * (`@kindgi/tools`, `@kindgi/guardrails`, `@kindgi/agents`,
+ * `@kindgi/flow`, `@kindgi/schema`) verbatim — no renaming, no
+ * behavior. Consumers reading those packages' docs find matching
+ * symbols here.
+ *
+ * The SDK facade is the recommended public developer surface. The
+ * individual packages remain importable directly.
+ *
+ * @module @kindgi/sdk/define
+ */
+
+// ---- Tools ----
+export {
+  defineTool,
+  defineToolAsync,
+  invokeTool,
+  registerToolSpecSynthesizer,
+} from '@kindgi/tools';
+export type {
+  DefinedTool,
+  DefineToolSpec,
+  HttpAuthSpec,
+  HttpHeaderSpec,
+  HttpMethod,
+  HttpRequestBodySpec,
+  HttpToolSpec,
+  InferInput,
+  InferOutput,
+  Tool,
+  ToolContext,
+  ToolManifest,
+  ToolSecretRef,
+  ToolSpec,
+  ToolSpecSynthesizer,
+} from '@kindgi/tools';
+
+// ---- Guardrails (checks) ----
+export { defineCheck } from '@kindgi/guardrails';
+export type { DefineCheckSpec, DefinedCheck, InferCheckConfig } from '@kindgi/guardrails';
+
+// ---- Agents ----
+export { defineAgent } from '@kindgi/agents';
+export type { Agent, DefineAgentSpec } from '@kindgi/agents';
+
+// ---- Flow ----
+//
+// `defineFlow` is the author-facing primitive that mirrors `defineTool`
+// / `defineCheck` / `defineAgent` — a thin wrapper over `loadFlow` that
+// runs the same validation gauntlet and returns `Result<Flow,
+// FlowError>`. Pack authors reach for `defineFlow` in TypeScript;
+// `loadFlow` remains the wire-form entry point for JSON coming off disk
+// / network.
+export { defineFlow } from '@kindgi/flow';
+export type {
+  EdgePolicy,
+  FanoutNode,
+  Flow,
+  FlowSpec,
+  LoopNode,
+  SubflowNode,
+} from '@kindgi/flow';
+
+// ---- Zod-optional helpers ----
+//
+// Direct access for callers that prefer to convert / inspect schemas
+// themselves rather than let `defineTool` / `defineCheck` do it implicitly.
+export { isZodSchema, toJSONSchema } from '@kindgi/schema';
+export type { AnySchema, ZodLikeSchema } from '@kindgi/schema';

package/src/index.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk` — public developer facade.
+ *
+ * Flat barrel that re-exports the three sub-paths for callers who prefer
+ * a single import: `import { defineTool, createClient, type RunId } from
+ * '@kindgi/sdk'`.
+ *
+ * Sub-paths are the primary developer-facing shape (`@kindgi/sdk/define`,
+ * `@kindgi/sdk/client`, `@kindgi/sdk/types`); this barrel is a
+ * convenience alias.
+ *
+ * @module @kindgi/sdk
+ */
+
+export * from './define.js';
+export * from './client.js';
+export * from './types.js';

package/src/runtime-config.ts

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Where an app's client finds its Kindgi runtime when `createClient` is
+ * called without `apiUrl` / `auth`:
+ *
+ *   1. `KINDGI_API_URL` and `KINDGI_API_TOKEN` from the environment;
+ *   2. outside production, the running `kindgi dev`, from the nearest
+ *      `.kindgirc.json` at or above the working directory (it records the
+ *      runtime's `apiUrl` and the dev `token`), with a one-time warning to
+ *      put them in the app's env file;
+ *   3. otherwise, an error that says what to set.
+ *
+ * Production (`NODE_ENV` or `KINDGI_ENV` set to `production`) never reads
+ * `.kindgirc.json`. Whatever the source, a token that differs from the
+ * running `kindgi dev`'s for the same `apiUrl` (the stale token after
+ * `kindgi dev --reset`) is warned about once.
+ *
+ * Node only: the file is read through `process.getBuiltinModule`, never a
+ * static `node:` import, so the module stays safe to bundle for browsers,
+ * where only explicit options apply.
+ */
+
+import type { AuthConfig, ClientOptions } from '@kindgi/client';
+
+/** The file `kindgi dev` writes in the pack directory. */
+export const DEV_RUNTIME_FILE = '.kindgirc.json';
+
+/** What a client needs from a running `kindgi dev`. */
+export interface DevRuntime {
+  readonly apiUrl: string;
+  readonly token: string;
+  /** The `.kindgirc.json` it came from. */
+  readonly path: string;
+}
+
+/** Where the lookup runs: the process's own environment by default (tests pass their own). */
+export interface RuntimeConfigContext {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** The directory the `.kindgirc.json` search starts from. */
+  readonly cwd: string | undefined;
+  readonly warn: (message: string) => void;
+}
+
+const ENV_FILE_HINT = 'your env file (.env / .env.local)';
+
+const warned = new Set<string>();
+
+function warnOnce(context: RuntimeConfigContext, key: string, message: string): void {
+  if (warned.has(key)) return;
+  warned.add(key);
+  context.warn(`[kindgi] ${message}`);
+}
+
+export function defaultContext(): RuntimeConfigContext {
+  const proc = typeof process === 'undefined' ? undefined : process;
+  return {
+    env: proc?.env ?? {},
+    cwd: typeof proc?.cwd === 'function' ? proc.cwd() : undefined,
+    warn: (message) => console.warn(message),
+  };
+}
+
+export function isProduction(env: RuntimeConfigContext['env']): boolean {
+  return env.NODE_ENV === 'production' || env.KINDGI_ENV === 'production';
+}
+
+/**
+ * The client options with every missing field resolved (see the module
+ * comment). Throws when no `apiUrl` or no token can be found.
+ */
+export function resolveClientOptions(
+  options: Partial<ClientOptions>,
+  context: RuntimeConfigContext = defaultContext(),
+): ClientOptions {
+  const { env } = context;
+  const dev = isProduction(env) ? undefined : findDevRuntime(context.cwd);
+
+  let apiUrl = options.apiUrl ?? nonEmpty(env.KINDGI_API_URL);
+  let auth: AuthConfig | undefined =
+    options.auth ??
+    (nonEmpty(env.KINDGI_API_TOKEN) !== undefined
+      ? { kind: 'apiToken', token: env.KINDGI_API_TOKEN as string }
+      : undefined);
+
+  if ((apiUrl === undefined || auth === undefined) && dev !== undefined) {
+    const used: string[] = [];
+    if (apiUrl === undefined) {
+      apiUrl = dev.apiUrl;
+      used.push('KINDGI_API_URL');
+    }
+    if (auth === undefined) {
+      auth = { kind: 'apiToken', token: dev.token };
+      used.push('KINDGI_API_TOKEN');
+    }
+    warnOnce(
+      context,
+      `fallback:${dev.path}`,
+      `Using the running kindgi dev from ${dev.path} for ${used.join(' and ')}. Set them in ${ENV_FILE_HINT}, and in production, where there's no ${DEV_RUNTIME_FILE}.`,
+    );
+  }
+
+  if (apiUrl === undefined || auth === undefined) {
+    const missing = [
+      ...(apiUrl === undefined ? ['KINDGI_API_URL'] : []),
+      ...(auth === undefined ? ['KINDGI_API_TOKEN'] : []),
+    ];
+    throw new Error(
+      `createClient(): ${missing.join(' and ')} ${missing.length === 1 ? "isn't" : "aren't"} set. Set ${missing.length === 1 ? 'it' : 'them'} in ${ENV_FILE_HINT}, or pass { apiUrl, auth }.${
+        isProduction(env)
+          ? ''
+          : ` In development, run \`kindgi dev\` in the app: it writes them to ${DEV_RUNTIME_FILE}, which the client reads.`
+      }`,
+    );
+  }
+
+  if (dev !== undefined && auth.kind === 'apiToken' && auth.token !== dev.token) {
+    if (sameUrl(apiUrl, dev.apiUrl)) {
+      warnOnce(
+        context,
+        `stale:${dev.path}:${dev.token}`,
+        `The API token doesn't match the running kindgi dev's (${dev.path}). After \`kindgi dev --reset\` the token changes: copy the new one into ${ENV_FILE_HINT}.`,
+      );
+    }
+  }
+
+  return { ...options, apiUrl, auth };
+}
+
+/**
+ * The running `kindgi dev`'s `apiUrl` and `token`, from the nearest
+ * `.kindgirc.json` at or above `from`; `undefined` when there's none, it
+ * can't be read, or the runtime can't read files (a browser).
+ */
+export function findDevRuntime(from: string | undefined): DevRuntime | undefined {
+  if (from === undefined) return undefined;
+  const fs = builtin<typeof import('node:fs')>('node:fs');
+  const path = builtin<typeof import('node:path')>('node:path');
+  if (fs === undefined || path === undefined) return undefined;
+  for (let dir = from; ; dir = path.dirname(dir)) {
+    const candidate = path.join(dir, DEV_RUNTIME_FILE);
+    if (fs.existsSync(candidate)) return readDevRuntime(fs, candidate);
+    if (path.dirname(dir) === dir) return undefined;
+  }
+}
+
+function readDevRuntime(fs: typeof import('node:fs'), file: string): DevRuntime | undefined {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8')) as Record<string, unknown>;
+    const apiUrl = parsed.apiUrl;
+    const token = parsed.token;
+    if (typeof apiUrl !== 'string' || apiUrl === '' || typeof token !== 'string' || token === '') {
+      return undefined;
+    }
+    return { apiUrl, token, path: file };
+  } catch {
+    return undefined;
+  }
+}
+
+function builtin<T>(id: string): T | undefined {
+  const proc = typeof process === 'undefined' ? undefined : process;
+  const get = (proc as { getBuiltinModule?: (id: string) => unknown } | undefined)
+    ?.getBuiltinModule;
+  return typeof get === 'function' ? (get.call(proc, id) as T | undefined) : undefined;
+}
+
+function nonEmpty(value: string | undefined): string | undefined {
+  return value === undefined || value === '' ? undefined : value;
+}
+
+function sameUrl(a: string, b: string): boolean {
+  return a.replace(/\/+$/, '') === b.replace(/\/+$/, '');
+}
+
+/** Tests only: forget which warnings were printed. */
+export function resetWarningsForTests(): void {
+  warned.clear();
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk/types` — branded IDs, framework-wide result envelope,
+ * pagination, refs, temporal + version primitives.
+ *
+ * Re-exports types from `@kindgi/types` under their own names. These
+ * are the workspace-wide identifiers callers pass across the SDK
+ * boundary.
+ *
+ * The /types sub-path is where branded identifiers live in the public
+ * facade.
+ *
+ * @module @kindgi/sdk/types
+ */
+
+export type {
+  BlobRef,
+  Brand,
+  ContentHash,
+  Cursor,
+  DatasetRef,
+  DurationMs,
+  ErrOf,
+  Filter,
+  IsoDuration,
+  OkOf,
+  Page,
+  Result,
+  SchemaMajor,
+  Semver,
+  SignatureValue,
+  Timestamp,
+  VersionedRef,
+} from '@kindgi/types';
+
+// ---- Branded IDs ----
+//
+// Re-exported individually rather than via `export type *` so the flat
+// barrel (`import { RunId } from '@kindgi/sdk'`) can see them —
+// `verbatimModuleSyntax` requires named type re-exports for `export *`
+// forwarding to work through the barrel.
+export type {
+  AgentId,
+  ApiTokenId,
+  ApprovalId,
+  ArtifactId,
+  AuditBundleId,
+  ComplianceEvidenceId,
+  ConversationId,
+  DatasetId,
+  EdgeId,
+  EventId,
+  FactId,
+  FixProposalId,
+  FlowId,
+  InstallationId,
+  GuardrailId,
+  KeyId,
+  LogEntryId,
+  NodeId,
+  ObservationId,
+  OrgId,
+  PackId,
+  PolicyId,
+  ProjectId,
+  ProvenanceId,
+  ProviderId,
+  ReviewerId,
+  RunId,
+  ScheduleId,
+  SessionId,
+  SigningKeyId,
+  SubscriptionId,
+  SupervisorId,
+  TeamId,
+  TenantId,
+  ThreadId,
+  ToolId,
+  TriggerId,
+  UserId,
+  WaitTokenId,
+  WebhookDeliveryId,
+  WebhookId,
+} from '@kindgi/types';

package/src/webhooks.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/sdk/webhooks` — receiving Kindgi's webhooks. Server only: it
+ * uses `node:crypto`, so it stays out of `/client` (browser-safe) and the
+ * flat barrel.
+ *
+ * Re-exports the Standard Webhooks helpers from `@kindgi/crypto`:
+ * `verifyWebhook` for a receiver, `generateWebhookSecret` for the secret an
+ * app registers by name, and `signWebhook` / `webhookHeaders` to test a
+ * receiver.
+ *
+ * @module @kindgi/sdk/webhooks
+ */
+
+export {
+  DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
+  generateWebhookSecret,
+  isStrongWebhookSecret,
+  signWebhook,
+  verifyWebhook,
+  WEBHOOK_HEADERS,
+  WEBHOOK_SECRET_MIN_BYTES,
+  WEBHOOK_SECRET_PREFIX,
+  webhookHeaders,
+} from '@kindgi/crypto';
+export type {
+  SignWebhookInput,
+  VerifyWebhookFailure,
+  VerifyWebhookInput,
+  VerifyWebhookResult,
+  WebhookRequestHeaders,
+} from '@kindgi/crypto';