sim 2.1.17 → 2.1.18-dev.130.1

package/dist/helpers.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Local copies of the shared helpers.
+ *
+ * `@sim/utils` is a private workspace package, so the published `sim` package
+ * cannot depend on it — importing it would resolve in the monorepo and fail for
+ * anyone installing from npm.
+ */
+/** Resolves after `ms` milliseconds. */
+export declare function sleep(ms: number): Promise<void>;

package/dist/http/client.d.ts

@@ -0,0 +1,173 @@
+import type { ResolvedProfile, StoredOAuthCredential } from '../config/index';
+/**
+ * A failure the CLI can explain. Anything thrown as a `SimApiError` is printed
+ * as a clean message and a non-zero exit; anything else escapes as a stack
+ * trace, which is the signal that the CLI itself is broken rather than the
+ * request.
+ */
+export declare class SimApiError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly details?: unknown;
+    readonly exitCode: number;
+    constructor(message: string, status: number, code?: string | null, details?: unknown, exitCode?: number);
+}
+/** `{ data, nextCursor }` — one page of a list. */
+export interface V2Page<T> {
+    data: T[];
+    nextCursor: string | null;
+}
+export interface RequestAllPagesOptions extends Omit<RequestOptions, 'query'> {
+    query?: Record<string, QueryValue>;
+    /** Server page size; callers choose one accepted by the endpoint contract. */
+    pageSize: number;
+    /** Maximum items to return. Omit to follow the cursor through the full list. */
+    limit?: number;
+}
+export type QueryValue = string | number | boolean | null | undefined;
+export type AuthRequirement = 'required' | 'optional';
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    /** Contract-declared headers, e.g. the `upload-token` a transfer is bound to. */
+    headers?: Record<string, string>;
+    /** Cancels both the initial request and any subsequent streaming body read. */
+    signal?: AbortSignal;
+    /** Self-hosted, auth-disabled routes may deliberately omit a local API key. */
+    auth?: AuthRequirement;
+}
+export interface WorkspaceOptions {
+    auth?: AuthRequirement;
+}
+/**
+ * Joins an endpoint and a route into a request URL.
+ *
+ * Concatenation rather than `new URL(path, endpoint)`, which is the trap it
+ * exists to avoid: a leading-slash path is absolute, so `new URL()` resolves it
+ * against the endpoint's ORIGIN and silently drops any path the endpoint
+ * carries. A deployment served under a prefix — `https://host/sim` behind a
+ * proxy that fronts several apps — would have every request rewritten to
+ * `https://host/...`, losing the prefix that identifies it.
+ *
+ * Empty values are skipped rather than sent blank so an omitted optional
+ * parameter reads as absent, not as the empty string.
+ */
+export declare function buildUrl(endpoint: string, path: string, query?: Record<string, QueryValue>): string;
+/**
+ * Statuses `fetch` would otherwise follow for us, and must not.
+ *
+ * A 301/302/303 is rewritten to a bodyless GET per the Fetch spec, so an
+ * endpoint that redirects (an apex host pointing at `www.`, say) keeps every
+ * read working through its query string while every write silently arrives with
+ * no body — the endpoint looks correct and only writes fail. Following a
+ * redirect would also hand the API key to whatever origin `Location` names.
+ */
+export declare const REDIRECT_STATUSES: Set<number>;
+/** The one instruction that resolves an elapsed request bound, wherever it surfaces. */
+export declare const RAISE_TIMEOUT_HINT = "Raise SIM_TIMEOUT_SECONDS, or set it to 0 to wait indefinitely.";
+/**
+ * Whether this is the CLI's own request bound elapsing.
+ *
+ * `AbortSignal.timeout` raises `TimeoutError`, while a caller's cancel raises
+ * `AbortError` — so this distinguishes a bound the user can raise from a stop
+ * the user asked for, which must keep reading as a cancellation.
+ */
+export declare function isRequestTimeout(error: unknown): boolean;
+/** Formats nested validation issues as readable, path-aware lines. */
+export declare function formatApiErrorDetails(details: unknown): string[];
+/**
+ * Renews an OAuth login and returns the new pair; injected so the HTTP client
+ * does not import the OAuth flow, which imports the client.
+ */
+export type OAuthRefresher = (profile: ResolvedProfile, current: StoredOAuthCredential) => Promise<StoredOAuthCredential>;
+export interface SimClientOptions {
+    refreshOAuth?: OAuthRefresher;
+}
+export declare class SimClient {
+    private readonly profile;
+    private readonly options;
+    private oauth;
+    private refreshing;
+    constructor(profile: ResolvedProfile, options?: SimClientOptions);
+    private resolveCredential;
+    /**
+     * One refresh at a time per process, shared by every request that finds the
+     * token expiring; the cross-process half lives behind the refresher.
+     */
+    private refreshOAuth;
+    /**
+     * The workspace every workspace-scoped command defaults to.
+     *
+     * By default this checks the key first even though it does not need one:
+     * commands resolve the workspace while building their query, so without this
+     * a brand-new install is told to set a workspace when the actual first step
+     * is logging in. Auth-disabled self-hosted protocols opt out explicitly.
+     */
+    requireWorkspace(explicit?: string, options?: WorkspaceOptions): string;
+    /**
+     * Makes a request without consuming its body. Authentication is required
+     * unless a self-hosted protocol explicitly opts out.
+     *
+     * JSON commands use {@link request}; streaming and binary protocols keep the
+     * raw response so they can process bytes incrementally. HTTP failures still
+     * become the same structured `SimApiError` either way.
+     */
+    requestRaw(path: string, options?: RequestOptions): Promise<Response>;
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    private send;
+    /**
+     * Explains a redirect instead of following it, naming the endpoint to switch to.
+     *
+     * The destination comes from `Location` resolved against the request URL, so a
+     * relative target works and no string surgery is done on the configured
+     * endpoint. A `Location` that is missing or unparseable still has to produce a
+     * sentence — the redirect is the finding either way.
+     */
+    private toRedirectError;
+}
+/**
+ * The endpoint a redirect implies, or null when it implies no change.
+ *
+ * Strips the request's own path from the target rather than taking
+ * `target.origin`, so a self-hosted endpoint carrying a path prefix
+ * (`https://host/sim`) keeps it. Naming the bare origin would hand back a value
+ * that is not an API root, and following that advice would break a deployment
+ * that was only ever one hostname away from working.
+ *
+ * Null when the target resolves to the endpoint already configured — a
+ * trailing-slash or path-normalization redirect keeps the origin, and telling
+ * someone to set the value they already have explains nothing.
+ */
+export declare function redirectEndpoint(endpoint: string, requestPath: string, target: URL): string | null;
+export interface PageProgress {
+    /** Call once a further page is known to be coming, with the count so far. */
+    advance: (fetched: number) => void;
+    /** Erases the line, if anything was ever written to it. */
+    finish: () => void;
+}
+/**
+ * Reports cursor progress on stderr while a list keeps paging.
+ *
+ * A long cursor is many sequential requests and reads as a hang, so say so — but
+ * only on a terminal, and only on stderr, because stdout is what gets piped to
+ * `jq`.
+ *
+ * Shared because the CLI pages in two places: {@link requestAllPages} for the
+ * `ls` commands, and the contract-driven loop in `runtime/execute`, which also
+ * has to carry a cursor in the body. Only one of them had the writer, and it was
+ * not the one nearly every `list --limit 0` goes through.
+ */
+export declare function pageProgress(): PageProgress;
+/** Rejects cursor cycles before a pager repeats requests or returns an unusable continuation. */
+export declare function assertCursorAdvances(cursor: string | null, seenCursors: Set<string>): void;
+/** Follows a standard v2 cursor envelope without duplicating pagination loops. */
+export declare function requestAllPages<T>(client: Pick<SimClient, 'request'>, path: string, options: RequestAllPagesOptions): Promise<T[]>;
+/**
+ * Substitutes `[id]`-style path segments.
+ *
+ * Values are percent-encoded: table and workspace ids are opaque, and a `/` or
+ * `?` inside one would otherwise silently retarget the request at a different
+ * endpoint.
+ */
+export declare function resolvePath(template: string, params?: Record<string, string>): string;

package/dist/http/environment.d.ts

@@ -0,0 +1,24 @@
+/** Test seam: notices are once-per-process, and each test needs a clean slate. */
+export declare function resetEnvironmentNotices(): void;
+/**
+ * Reports a proxy the request will not actually go through.
+ *
+ * Node's `fetch` ignores `HTTP(S)_PROXY` unless `NODE_USE_ENV_PROXY` opts in,
+ * and older releases ignore them outright — so on a network that only reaches
+ * the API through a proxy, every command fails to connect while the variable
+ * that would have fixed it is already set. The CLI cannot enable the support
+ * from inside the process (Node reads the flag at startup), so it says what to
+ * do instead of proxying itself, which would mean bundling an HTTP stack for a
+ * setting the platform now owns.
+ */
+export declare function warnIfProxyIgnored(env?: NodeJS.ProcessEnv, version?: string): void;
+/**
+ * Reports an API key about to cross the network in cleartext.
+ *
+ * A warning rather than a refusal: `http://` is the documented way to reach a
+ * local dev server, and an internal deployment terminating TLS at a gateway is
+ * a real deployment, not a mistake to block. Loopback is silent because that is
+ * the documented case; anything else means the key is on the wire in the clear,
+ * which is worth one line.
+ */
+export declare function warnIfCredentialOverCleartext(endpoint: string, hasCredential: boolean): void;

package/dist/http/ndjson.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Parses a newline-delimited JSON response incrementally and releases its
+ * reader when the consumer reaches a terminal event or stops early.
+ */
+export declare function readNdjson(body: ReadableStream<Uint8Array> | null, protocol: string): AsyncGenerator<unknown>;