@caitlyn-ai/sdk-core 0.0.1 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caitlyn-ai/sdk-core",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "The runtime core of the Caitlyn TypeScript SDK: the Caitlyn REST JSON protocol, sign-in, retries, server-sent events, waiters and telemetry.",
   "license": "Apache-2.0",
   "homepage": "https://build.caitlyn.ai",
@@ -15,7 +15,6 @@
   "types": "./dist-types/index.d.ts",
   "exports": {
     ".": {
-      "caitlyn-source": "./src/index.ts",
       "types": "./dist-types/index.d.ts",
       "import": "./dist-es/index.mjs",
       "require": "./dist-cjs/index.cjs"

package/dist-types/auth.d.ts

@@ -1,140 +0,0 @@
-import type { Pluggable, TokenIdentity } from '@smithy/types';
-import type { AwsCredentialSource } from './aws.js';
-/** Tokens the `oauth` mode keeps. `expiresAt` is milliseconds since the epoch. */
-export interface OAuthTokens {
-    accessToken: string;
-    refreshToken?: string;
-    expiresAt?: number;
-    scope?: string;
-}
-/** Where the `oauth` mode keeps tokens between processes, for example encrypted on a server. */
-export interface TokenStore {
-    load(): Promise<OAuthTokens | undefined> | OAuthTokens | undefined;
-    save(tokens: OAuthTokens): Promise<void> | void;
-    clear(): Promise<void> | void;
-}
-export type AuthOptions = {
-    mode: 'token';
-    token: string;
-} | {
-    mode: 'clientCredentials';
-    clientId: string;
-    clientSecret: string;
-    scopes?: string[];
-    resource?: string;
-} | {
-    mode: 'oauth';
-    clientId: string;
-    /** For a confidential client on a server; omit in a browser. */
-    clientSecret?: string;
-    redirectUri?: string;
-    scopes?: string[];
-    resource?: string;
-    /** Default: kept in memory for the life of the client. */
-    tokenStore?: TokenStore;
-} | {
-    mode: 'awsIam';
-    /** The regional STS endpoint to use. Default: AWS_REGION, then AWS_DEFAULT_REGION. */
-    region?: string;
-    /** Default: environment variables, then the container credentials endpoint. Accepts any @aws-sdk provider. */
-    credentials?: AwsCredentialSource;
-    signingAlgorithm?: 'ES384' | 'RS256';
-    /** Lifetime of the AWS-signed token, at most 300 (the default). */
-    durationSeconds?: number;
-    /** The audience the AWS token is minted for. Default: the workspace resource URL. */
-    audience?: string;
-    stsEndpoint?: string;
-} | {
-    mode: 'workloadIdentity';
-    /** Returns the workload's current identity token, for example a GitLab CI id_tokens variable. */
-    token: () => string | Promise<string>;
-    resource?: string;
-} | {
-    mode: 'session';
-    /** A session cookie, for server-side use. In a browser leave it out: the browser sends its own. */
-    cookie?: string;
-    /** Sent as Origin on every write. Default: the workspace URL. */
-    origin?: string;
-};
-/** A sign-in failure: the token endpoint's OAuth error, or a failure to get the identity it exchanges. */
-export declare class CaitlynAuthError extends Error {
-    /** The OAuth error code (`invalid_client`, `invalid_grant`…), or `sign_in_required`. */
-    readonly code: string;
-    readonly status?: number | undefined;
-    readonly requestId?: string | undefined;
-    readonly name = "CaitlynAuthError";
-    constructor(message: string, 
-    /** The OAuth error code (`invalid_client`, `invalid_grant`…), or `sign_in_required`. */
-    code: string, status?: number | undefined, requestId?: string | undefined);
-}
-/** The audience of a workspace's tokens: its resource URL, https://<workspace>/api/v3. */
-export declare const workspaceAudience: (workspace: string) => string;
-/** A workspace given as a hostname or a URL, as its bare hostname. */
-export declare const workspaceHost: (workspace: string) => string;
-/** What `client.auth` offers: the current token, and the `oauth` mode's sign-in steps. */
-export declare class AuthSession {
-    readonly options: AuthOptions;
-    /** Where the token endpoint is: the client's endpoint, which an override may move (a proxy, a local app). */
-    readonly endpoint: string;
-    /** The workspace hostname. Like an AWS region, it decides the endpoint and the token audience. */
-    readonly workspace: string;
-    private readonly fetchFn;
-    private cached?;
-    /** The token the server last refused with a 401, so `oauth` never reloads it from the store. */
-    private refused?;
-    private inflight?;
-    private memoryTokens?;
-    readonly tokenEndpoint: string;
-    readonly authorizationEndpoint: string;
-    /** The workspace's resource URL, https://<workspace>/api/v3: the audience every token is bound to. */
-    readonly resource: string;
-    /** https://<workspace>: the default Origin for session writes. */
-    readonly workspaceUrl: string;
-    constructor(options: AuthOptions, 
-    /** Where the token endpoint is: the client's endpoint, which an override may move (a proxy, a local app). */
-    endpoint: string, 
-    /** The workspace hostname. Like an AWS region, it decides the endpoint and the token audience. */
-    workspace: string, fetchFn?: typeof fetch);
-    get mode(): "token" | "clientCredentials" | "oauth" | "awsIam" | "workloadIdentity" | "session";
-    /** The bearer token for the next request: cached, or fetched once however many calls ask at the same time. */
-    token(): Promise<string>;
-    /** Forgets the cached token, so the next call signs in again (done once after a 401). */
-    invalidate(): void;
-    /** Whether a 401 is worth one more try with a new token. */
-    get canRefresh(): boolean;
-    /** Starts sign-in (`oauth` mode): the URL to send the person to, and the state and PKCE verifier to keep. */
-    authorizationUrl(opts?: {
-        state?: string;
-        scopes?: string[];
-        redirectUri?: string;
-    }): Promise<{
-        url: string;
-        state: string;
-        codeVerifier: string;
-    }>;
-    /** Finishes sign-in (`oauth` mode): checks state, exchanges the code and saves the tokens. */
-    handleCallback(p: {
-        code: string;
-        state?: string;
-        expectedState?: string;
-        codeVerifier: string;
-        redirectUri?: string;
-    }): Promise<OAuthTokens>;
-    /** Signs out (`oauth` mode): revokes the refresh token where possible and clears the store. */
-    signOut(): Promise<void>;
-    private oauth;
-    private clientParams;
-    private loadTokens;
-    private saveTokens;
-    private fetchToken;
-    private exchange;
-    private requestToken;
-}
-/**
- * The generated client's `token` identity provider. It reports the token as already near expiry, so Smithy's
- * memoisation asks again on every request and AuthSession's own cache (which knows the real expiry, and can
- * be invalidated after a 401) decides.
- */
-export declare const tokenIdentityProvider: (auth: AuthSession) => () => Promise<TokenIdentity>;
-/** Session headers, and one retry with a new token after a 401. */
-export declare function getCaitlynAuthPlugin(auth: AuthSession): Pluggable<any, any>;

package/dist-types/aws.d.ts

@@ -1,43 +0,0 @@
-export interface AwsCredentials {
-    accessKeyId: string;
-    secretAccessKey: string;
-    sessionToken?: string;
-    /** When the credentials stop working; the SDK fetches new ones a minute before. */
-    expiration?: Date;
-}
-export type AwsCredentialSource = AwsCredentials | (() => Promise<AwsCredentials> | AwsCredentials);
-/** RFC 3986 encoding, as Signature Version 4 requires (encodeURIComponent leaves !'()* alone). */
-export declare const awsEncode: (s: string) => string;
-export interface SignableRequest {
-    method: string;
-    url: URL;
-    headers: Record<string, string>;
-    body: string;
-}
-/**
- * Signs a request with AWS Signature Version 4 (header form) and returns the headers to send, including
- * `authorization`, `x-amz-date`, `x-amz-content-sha256` and, for temporary credentials, `x-amz-security-token`.
- */
-export declare function signV4(req: SignableRequest, creds: AwsCredentials, region: string, service: string, now?: Date): Promise<Record<string, string>>;
-/**
- * The default credential source: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (with AWS_SESSION_TOKEN), as AWS
- * Lambda and CI runners set them; otherwise the container credentials endpoint
- * (AWS_CONTAINER_CREDENTIALS_FULL_URI or _RELATIVE_URI), as ECS, Fargate and AgentCore runtimes set it.
- */
-export declare function defaultAwsCredentials(fetchFn?: typeof fetch): Promise<AwsCredentials>;
-export interface WebIdentityTokenRequest {
-    region: string;
-    audience: string;
-    credentials: AwsCredentials;
-    signingAlgorithm?: 'ES384' | 'RS256';
-    durationSeconds?: number;
-    /** Overrides https://sts.{region}.amazonaws.com/ (tests, FIPS or VPC endpoints). */
-    stsEndpoint?: string;
-    fetch?: typeof fetch;
-    signal?: AbortSignal;
-}
-/** Calls STS GetWebIdentityToken (outbound identity federation) on a regional endpoint and returns the JWT. */
-export declare function getWebIdentityToken(r: WebIdentityTokenRequest): Promise<{
-    token: string;
-    expiration?: Date;
-}>;

package/dist-types/client.d.ts

@@ -1,62 +0,0 @@
-import type { TracerProvider } from '@opentelemetry/api';
-import { CaitlynRetryStrategy } from './retry.js';
-import { AuthSession, type AuthOptions } from './auth.js';
-export interface CaitlynOptions {
-    /**
-     * The workspace hostname, for example "your-company.getcaitlyn.ai". Like an AWS region, it decides where
-     * requests go (https://<workspace>/api) and the audience every token is bound to (https://<workspace>/api/v3).
-     */
-    workspace: string;
-    /** How the client signs in: token, clientCredentials, oauth, awsIam, workloadIdentity or session. */
-    auth: AuthOptions;
-    /** The fetch the sign-in requests use (token endpoint, STS, container credentials). Default: global fetch. */
-    fetch?: typeof fetch;
-    /**
-     * Overrides the base URL the operation paths (/v3/…) and the token endpoint (/oauth/token) are appended to,
-     * for a proxy or a local app. Default: https://{workspace}/api. It never changes the token audience.
-     */
-    endpoint?: string;
-    maxAttempts?: number;
-    /** Longest Retry-After the SDK waits for (default 60 000 ms); above it the call fails at once. */
-    maxRetryDelayMs?: number;
-    telemetry?: {
-        tracerProvider?: TracerProvider;
-        enabled?: boolean;
-    };
-}
-export interface CallOptions {
-    signal?: AbortSignal;
-}
-/** The base URL of a workspace's API: its hostname, over HTTPS, with the /api prefix every Caitlyn route has. */
-export declare function workspaceEndpoint(workspace: string): string;
-/** The sign-in session for a set of options: what `client.auth` is. */
-export declare function createAuth(opts: CaitlynOptions): AuthSession;
-/** The generated client's configuration for a set of options. */
-export declare function clientConfig(opts: CaitlynOptions, auth?: AuthSession): {
-    retryStrategy?: CaitlynRetryStrategy | undefined;
-    maxAttempts?: number | undefined;
-    /** The workspace this client is for; readable as client.config.workspace. */
-    workspace: string;
-    endpoint: string;
-    token: () => Promise<import("@smithy/types").TokenIdentity>;
-};
-/** One problem with one request member or query parameter, on a 400 VALIDATION_FAILED. */
-export interface CaitlynFieldError {
-    pointer?: string;
-    parameter?: string;
-    code: string;
-    detail?: string;
-}
-/** The RFC 9457 fields every Caitlyn error carries (PROTOCOL.md 6.3). */
-export interface CaitlynErrorFields {
-    status?: number;
-    code?: string;
-    type?: string;
-    title?: string;
-    detail?: string;
-    requestId?: string;
-    retryAfterSeconds?: number;
-    errors?: CaitlynFieldError[];
-    /** The response body as received, as text: the only view of a body that is not problem details (PROTOCOL.md 6.3). */
-    rawBody?: string;
-}

package/dist-types/endpoint.d.ts

@@ -1,4 +0,0 @@
-import type { EndpointV2 } from '@smithy/types';
-export declare const caitlynEndpointProvider: (params: {
-    endpoint?: string;
-}) => EndpointV2;

package/dist-types/plugin.d.ts

@@ -1,21 +0,0 @@
-import type { Pluggable } from '@smithy/types';
-export declare const CAITLYN_SDK_USER_AGENT_PREFIX = "caitlyn-sdk-ts";
-export declare class NotSupportedByServer extends Error {
-    readonly operation: string;
-    readonly requires: string;
-    readonly server: string;
-    constructor(operation: string, requires: string, server: string);
-}
-/**
- * @param options.sdkModel the highest @since in the model: the server release this SDK was generated against
- * @param options.retrySafeOperations operations that are @readonly, @idempotent or have an @idempotencyToken member
- * @param options.since `Operation=5.120.0` and `Operation.member=5.124.0` entries from the model's @since traits
- */
-export declare function getCaitlynSdkPlugin(config: {
-    caitlynSdkVersion?: string;
-    customUserAgent?: string;
-}, options: {
-    sdkModel: string;
-    retrySafeOperations: string[];
-    since?: string[];
-}): Pluggable<any, any>;

package/dist-types/protocol.d.ts

@@ -1,24 +0,0 @@
-import { HttpBindingProtocol, HttpInterceptingShapeDeserializer, HttpInterceptingShapeSerializer, JsonCodec2 } from '@smithy/core/protocols';
-import { TypeRegistry } from '@smithy/core/schema';
-import type { HandlerExecutionContext, HttpRequest, HttpResponse, MetadataBearer, OperationSchema, ResponseMetadata, SerdeFunctions } from '@smithy/types';
-/** An output with the parsed response body, including fields this SDK version does not model. */
-export type WithRaw<T> = T & {
-    readonly raw?: Record<string, unknown>;
-};
-export declare class CaitlynRestJsonProtocol extends HttpBindingProtocol {
-    protected serializer: HttpInterceptingShapeSerializer<import("@smithy/types").$ShapeSerializer<Uint8Array<ArrayBufferLike>>>;
-    protected deserializer: HttpInterceptingShapeDeserializer<import("@smithy/types").$ShapeDeserializer<string>>;
-    private readonly codec;
-    constructor({ defaultNamespace, errorTypeRegistries }: {
-        defaultNamespace: string;
-        errorTypeRegistries?: TypeRegistry[];
-    });
-    getShapeId(): string;
-    getDefaultContentType(): string;
-    getPayloadCodec(): JsonCodec2;
-    setSerdeContext(serdeContext: SerdeFunctions): void;
-    serializeRequest<Input extends object>(operationSchema: OperationSchema, input: Input, context: Parameters<HttpBindingProtocol['serializeRequest']>[2]): Promise<HttpRequest>;
-    deserializeResponse<Output extends MetadataBearer>(operationSchema: OperationSchema, context: HandlerExecutionContext & SerdeFunctions, response: HttpResponse): Promise<Output>;
-    protected deserializeMetadata(response: HttpResponse): ResponseMetadata;
-    protected handleError(_operationSchema: OperationSchema, context: HandlerExecutionContext & SerdeFunctions, response: HttpResponse, dataObject: Record<string, unknown>, metadata: ResponseMetadata): Promise<never>;
-}

package/dist-types/retry.d.ts

@@ -1,11 +0,0 @@
-import type { Provider, RetryErrorInfo, RetryStrategyV2, RetryToken } from '@smithy/types';
-export declare const NO_RETRY: unique symbol;
-export declare class CaitlynRetryStrategy implements RetryStrategyV2 {
-    private readonly maxRetryDelayMs;
-    readonly mode = "standard";
-    private readonly maxAttempts;
-    constructor(maxAttempts?: number | Provider<number>, maxRetryDelayMs?: number);
-    acquireInitialRetryToken(): Promise<RetryToken>;
-    refreshRetryTokenForRetry(token: RetryToken, info: RetryErrorInfo): Promise<RetryToken>;
-    recordSuccess(): void;
-}

package/dist-types/sse.d.ts

@@ -1,6 +0,0 @@
-export interface SseMessage {
-    id?: string;
-    event: string;
-    data: string;
-}
-export declare function parseSse(body: AsyncIterable<Uint8Array | string>): AsyncGenerator<SseMessage>;

package/dist-types/stream.d.ts

@@ -1,34 +0,0 @@
-export interface SseSpec {
-    /** SSE `event:` names this SDK knows (the union members' jsonNames). Others are skipped. */
-    readonly known: ReadonlySet<string>;
-    /** The event that ends the stream successfully, and the member finalMessage() returns. */
-    readonly final?: {
-        event: string;
-        member: string;
-    };
-    /** The event carrying RFC 9457 problem details; it ends the stream with a thrown error. */
-    readonly errorEvent?: string;
-    /** Builds the typed error for an error event. */
-    readonly toError: (problem: Record<string, unknown>) => Error;
-}
-type Body = AsyncIterable<Uint8Array>;
-export declare class SseStream<E extends {
-    type: string;
-}, F = never> implements AsyncIterable<E> {
-    private readonly spec;
-    private readonly open;
-    private readonly resume;
-    private readonly signal?;
-    private readonly maxReconnects;
-    private finalValue?;
-    private consumed;
-    private readonly seen;
-    lastEventId?: string;
-    reconnects: number;
-    constructor(spec: SseSpec, open: () => Promise<Body>, resume: ((lastEventId: string | undefined) => Promise<Body>) | undefined, signal?: AbortSignal | undefined, maxReconnects?: number);
-    private aborted;
-    [Symbol.asyncIterator](): AsyncGenerator<E>;
-    /** Drains the stream if needed and returns the final event's member. */
-    finalMessage(): Promise<F>;
-}
-export {};

package/dist-types/telemetry.d.ts

@@ -1,3 +0,0 @@
-import type { Pluggable } from '@smithy/types';
-import { type TracerProvider } from '@opentelemetry/api';
-export declare function getCaitlynTelemetryPlugin(provider?: TracerProvider): Pluggable<any, any>;

package/dist-types/upload.d.ts

@@ -1,12 +0,0 @@
-export interface UploadSlot {
-    uploadUrl: string;
-    uploadMethod: string;
-    requiredHeaders: Record<string, string>;
-}
-export interface UploadMeta {
-    fileName: string;
-    contentType: string;
-    byteSize: number;
-    sha256: string;
-}
-export declare function uploadFile<S extends UploadSlot>(file: Blob, fileName: string, reserve: (meta: UploadMeta) => Promise<S>, toError: (problem: Record<string, unknown>) => Error, signal?: AbortSignal): Promise<S>;

package/dist-types/waiter.d.ts

@@ -1,30 +0,0 @@
-export type WaiterState = 'success' | 'failure' | 'retry';
-export interface WaiterOptions {
-    /** Stops waiting and throws the signal's reason (use AbortSignal.timeout() for a deadline). */
-    signal?: AbortSignal;
-    /** The longest the waiter waits in total, in milliseconds. Default: no limit beyond the signal. */
-    maxWaitMs?: number;
-    /** Default 2 000 ms (Smithy's default minDelay). */
-    minDelayMs?: number;
-    /** Default 120 000 ms (Smithy's default maxDelay). */
-    maxDelayMs?: number;
-}
-/** A waiter ended in a failure state, or ran out of time. `last` is the last output or error it saw. */
-export declare class WaiterError extends Error {
-    readonly reason: 'failure' | 'timeout';
-    readonly last: unknown;
-    readonly attempts: number;
-    readonly name = "WaiterError";
-    constructor(message: string, reason: 'failure' | 'timeout', last: unknown, attempts: number);
-}
-/**
- * Calls `read` until `accept` says success (returns the output) or failure (throws WaiterError).
- * `accept` sees either `{output}` or `{error}`; returning undefined for an error rethrows it.
- */
-export declare function waitUntil<T>(name: string, read: (signal?: AbortSignal) => Promise<T>, accept: (r: {
-    output: T;
-    error?: undefined;
-} | {
-    output?: undefined;
-    error: unknown;
-}) => WaiterState | undefined, opts?: WaiterOptions): Promise<T>;