@kallfi/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kallfi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+# Kallfi SDKs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed server-side TypeScript and Python clients for the canonical Kallfi API.
+The 0.2.0 source supports 38 operations: 31 Account operations and seven organization-resource operations. Availability, current membership, provider policy and economic admission remain server-owned. Explicit workspace support is negotiated before dispatch and safely rejects older servers.
+
+## Install
+
+Release package names are `@kallfi/sdk` on npm and `kallfi-sdk` on PyPI; Python imports remain `kallfi`. Registry availability must be checked for the selected release version.
+
+```sh
+npm install @kallfi/sdk
+pnpm add @kallfi/sdk
+yarn add @kallfi/sdk
+python -m pip install kallfi-sdk
+uv add kallfi-sdk
+uv pip install kallfi-sdk
+```
+
+Keep API credentials on trusted application servers. Never embed them in distributed client code.
+
+## JavaScript / TypeScript
+
+```ts
+import { Kallfi } from "@kallfi/sdk";
+
+const kallfi = new Kallfi({ apiKey: process.env.KALLFI_API_KEY! });
+
+const accepted = await kallfi.souls.create(
+  {
+    external_soul_id: "performer-17",
+    kind: "human",
+    description: "An energetic live host with warm, concise delivery.",
+    source_asset_ids: [],
+  },
+  { idempotencyKey: crypto.randomUUID() },
+);
+
+const operation = await kallfi.operations.wait(accepted.operation.operation_id, {
+  timeoutMs: 120_000,
+});
+```
+
+Request and response types are generated from `openapi/openapi.v1.json` and are
+exported by the root package. API failures throw `KallfiApiError`; branch on its
+stable `code`, not its human-readable message.
+
+## Python
+
+```python
+import os
+import uuid
+
+from kallfi import Kallfi, SoulCreateRequest
+
+with Kallfi(api_key=os.environ["KALLFI_API_KEY"]) as kallfi:
+    accepted = kallfi.souls.create(
+        SoulCreateRequest(
+            external_soul_id="performer-17",
+            kind="human",
+            description="An energetic live host with warm, concise delivery.",
+            source_asset_ids=[],
+        ),
+        idempotency_key=str(uuid.uuid4()),
+    )
+    operation = kallfi.operations.wait(accepted.operation.operation_id, timeout=120.0)
+```
+
+API failures raise `KallfiAPIError`; use stable codes and request metadata rather than human-readable messages.
+
+## Surface
+
+Both SDKs retain these seven typed resource methods alongside generated dispatch for all 38 canonical operations:
+
+- `sourceAssets.create` / `source_assets.create`
+- `souls.create`, `souls.retrieve`, and `souls.update`
+- `souls.createResponse` / `souls.create_response`
+- `souls.createGeneration` / `souls.create_generation`
+- `operations.retrieve`
+
+Mutation methods require an explicit idempotency key. The clients do not retry
+implicitly, calculate prices, infer capabilities, or reproduce server-side
+safety, quota, lifecycle, and quote rules.
+
+## Develop
+
+```sh
+# JavaScript: generate/check contract types, test, type-check, and build
+npm ci
+npm run check
+npm pack --dry-run
+
+# Python: sync the lock, check generated models, lint/type-check/test, and build
+uv sync --directory python --locked --all-extras
+uv run --directory python ruff check src tests
+uv run --directory python mypy src
+uv run --directory python pytest
+uv build --directory python
+```
+
+The repository pins the canonical contract digest and verifies generated-code
+drift in CI. See [openapi/README.md](openapi/README.md) for provenance.
+
+## Publishing
+
+The manual workflows use GitHub OIDC trusted publishing and contain no registry
+tokens. They remain skipped until maintainers create protected `npm` and `pypi`
+repository environments, establish package ownership/trusted publishers at both
+registries, and explicitly set the matching `*_TRUSTED_PUBLISHING_ENABLED`
+repository variable to `true`. The canonical registry package name is `@kallfi/sdk` for npm and `kallfi-sdk` for PyPI. Both workflows verify an existing immutable tag
+whose `vX.Y.Z` version matches both packages.
+
+## License
+
+[MIT](LICENSE)
+
+## Universal API and workspace selection
+
+SDK 0.2.0 interface:
+
+```ts
+const client = new Kallfi({
+  apiKey: process.env.KALLFI_API_KEY!,
+  surface: "nsfw-disabled",
+  // Omit workspaceId for Personal. Explicit UUID selects a currently authorized organization.
+});
+const response = await client.operation("getAccountCreatorPlan", {
+  body: { query: {}, body: {} },
+}, { idempotencyKey: crypto.randomUUID() });
+// response: { status, data, requestId?, retryAfter?, location?, contentType? }
+```
+
+Operation arguments are the canonical endpoint path/query/body envelope, not a second admission or pricing model. POST read actions still require idempotency keys. Inspect the current canonical operation schema before selecting body fields; the snippet demonstrates transport shape only. Existing request/resource methods still return body data.
+
+The default origin is acr.kallfi.com or acr.kallfi.red by surface. Explicit api.kallfi.com/red origins remain supported; unknown origins and explicit surface mismatch are rejected. An explicit workspace selector emits one validated X-Kallfi-Workspace-ID. Before every selected-workspace request the SDK performs one uncached unauthenticated GET /v1/capabilities on the same origin, sharing the overall timeout and caller signal. A missing, old, HTML, redirected or mismatched capability response raises KallfiWorkspaceUnsupportedError (code workspace_capability_unsupported) without dispatching the business request. The error carries no fabricated HTTP status. MCP uses this same SDK boundary and performs no second handshake. Capability support is not membership, role, scope, balance or business authorization; those remain server-owned.
+
+Account-scoped operations reject a configured workspace selector locally. Personal omission does not perform a capability probe. No automatic mutation retry, selector override or key issuance is added. Redirects/login HTML are rejected. JSON response reads are bounded (2MiB default, configurable up to16MiB); capability evidence is bounded4096bytes. Timeout/cancellation includes response consumption and polling sleeps; raw server messages, details and transport causes are not retained by internal errors. Errors expose bounded safe code/status/requestId/retryAfter only. No media upload, economic terms or provider authority is inferred from this transport.
+
+Generated types and all38 operation descriptors come from the same SHA-pinned OpenAPI snapshot. npm run generate regenerates both; npm run check:generated detects drift in either. Versioning, release qualification and publication remain owner-selected work.
+
+## MCP integration
+
+The published MCP server remains `@kallfi/mcp`. Its next compatible release uses `@kallfi/sdk` as the single HTTP transport. Start the selected published MCP version with `npx @kallfi/mcp`; do not assume older releases already use the new SDK.

package/dist/client.d.ts

@@ -0,0 +1,109 @@
+import { type KallfiOperationId } from "./operations.js";
+import type { GenerationCreateRequest, Operation, OperationAcceptedResponse, SoulAcceptedResponse, SoulCreateRequest, Soul, SoulUpdateAcceptedResponse, SoulUpdateRequest, SourceAssetAcceptedResponse, SourceAssetCreateRequest } from "./generated.js";
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export type KallfiSurface = "nsfw-disabled" | "nsfw-enabled";
+export interface OperationArguments {
+    path?: Readonly<Record<string, string>>;
+    query?: Readonly<Record<string, string | number | boolean | ReadonlyArray<string | number | boolean>>>;
+    body?: unknown;
+}
+export type OperationOptions = Pick<DetailedRequestOptions, "idempotencyKey" | "signal" | "timeoutMs">;
+export interface DetailedRequestOptions {
+    body?: unknown;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface DetailedResponse<T> {
+    status: number;
+    data: T;
+    requestId?: string;
+    retryAfter?: string;
+    location?: string;
+    contentType?: string;
+}
+export interface KallfiOptions {
+    surface?: KallfiSurface;
+    workspaceId?: string;
+    maxResponseBytes?: number;
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+}
+export interface MutationOptions {
+    idempotencyKey: string;
+}
+export interface WaitOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    signal?: AbortSignal;
+}
+export declare class KallfiWorkspaceUnsupportedError extends Error {
+    readonly code: "workspace_capability_unsupported";
+    constructor();
+}
+export declare class KallfiNetworkError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare class KallfiTimeoutError extends KallfiNetworkError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, cause?: unknown);
+}
+export declare class KallfiApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly request_id?: string;
+    readonly details?: Readonly<Record<string, string>>;
+    readonly retry_after?: string;
+    constructor(options: {
+        status: number;
+        code: string;
+        message: string;
+        request_id?: string;
+        details?: Readonly<Record<string, string>>;
+        retry_after?: string;
+    });
+    get requestId(): string | undefined;
+    get retryAfter(): string | undefined;
+}
+export declare class Kallfi {
+    readonly sourceAssets: SourceAssetsResource;
+    readonly souls: SoulsResource;
+    readonly operations: OperationsResource;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetcher;
+    private readonly timeoutMs;
+    private readonly workspaceId?;
+    private readonly maxResponseBytes;
+    constructor(options: KallfiOptions);
+    static fromEnv(options?: Omit<KallfiOptions, "apiKey">): Kallfi;
+    operation<T = unknown>(operationId: KallfiOperationId, args?: OperationArguments, options?: OperationOptions): Promise<DetailedResponse<T>>;
+    request<T>(method: string, path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
+    requestDetailed<T>(method: string, path: string, options?: DetailedRequestOptions): Promise<DetailedResponse<T>>;
+    private requireWorkspaceCapability;
+    private performRequest;
+}
+export declare class SourceAssetsResource {
+    private readonly client;
+    constructor(client: Kallfi);
+    create(body: SourceAssetCreateRequest, options: MutationOptions | string): Promise<SourceAssetAcceptedResponse>;
+}
+export declare class SoulsResource {
+    private readonly client;
+    constructor(client: Kallfi);
+    create(body: SoulCreateRequest, options: MutationOptions | string): Promise<SoulAcceptedResponse>;
+    retrieve(soulId: string): Promise<Soul>;
+    update(soulId: string, body: SoulUpdateRequest, options: MutationOptions | string): Promise<SoulUpdateAcceptedResponse>;
+    createResponse(soulId: string, body: import("./generated.js").ResponseCreateRequest, options: MutationOptions | string): Promise<OperationAcceptedResponse>;
+    createGeneration(soulId: string, body: GenerationCreateRequest, options: MutationOptions | string): Promise<OperationAcceptedResponse>;
+}
+export declare class OperationsResource {
+    private readonly client;
+    constructor(client: Kallfi);
+    retrieve(operationId: string): Promise<Operation>;
+    wait(operationId: string, options?: WaitOptions): Promise<Operation>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}