@rebilly/api 0.0.0 → 0.1.1

package/dist/runtime/types.d.ts

@@ -0,0 +1,349 @@
+/**
+ * The public type surface of the client runtime — `@redocly/client-generator`'s
+ * app-facing runtime module. Pure types, no runtime code (excluded from coverage).
+ * The generator emits `OPERATIONS` literals typed
+ * `satisfies Record<string, OperationDescriptor>` against this module, so an
+ * incompatible runtime/generated pair fails the consumer's build (the semver skew guard).
+ */
+/** How one operation parameter is sent: its location plus OpenAPI query-serialization hints. */
+export type ParamSpec = {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    style?: 'form' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
+    explode?: boolean;
+    allowReserved?: boolean;
+};
+/** One security scheme, denormalized onto the operation (`scheme` names the spec's scheme). */
+export type SecuritySpec = {
+    scheme: string;
+    kind: 'bearer' | 'basic';
+} | {
+    scheme: string;
+    kind: 'apiKey';
+    name: string;
+    in: 'header' | 'query' | 'cookie';
+};
+/**
+ * How to auto-iterate a paginated operation (drives its `.pages()`/`.items()` members).
+ * `nextCursor`, `nextLink`, and `items` are RFC 6901 JSON pointers into the page (response) value.
+ */
+export type PaginationSpec = {
+    style: 'cursor';
+    /** The query param the iterator advances with the response's cursor. */
+    param: string;
+    /** Optional page-size query param (recorded for tooling; never set by the runtime). */
+    limitParam?: string;
+    /** Pointer to the next cursor in the page. */
+    nextCursor: string;
+    /** Optional pointer to a boolean "more pages" flag — `false` stops iteration. */
+    hasMore?: string;
+    /** Pointer to the page's item array. */
+    items: string;
+} | {
+    style: 'offset' | 'page';
+    /** The numeric query param the iterator advances. */
+    param: string;
+    /** Optional page-size query param (recorded for tooling; never set by the runtime). */
+    limitParam?: string;
+    /** Pointer to the page's item array. */
+    items: string;
+} | {
+    /** RFC 8288: follow the response's `Link` header `rel="next"`; stop when absent. */
+    style: 'link';
+    /** Optional page-size query param (recorded for tooling; never set by the runtime). */
+    limitParam?: string;
+    /** Pointer to the page's item array. */
+    items: string;
+} | {
+    /** Follow the next page's URL at `nextLink` in the page; stop when it is absent. */
+    style: 'body-link';
+    /** Optional page-size query param (recorded for tooling; never set by the runtime). */
+    limitParam?: string;
+    /** Pointer to the next page's URL in the page. */
+    nextLink: string;
+    /** Pointer to the page's item array. */
+    items: string;
+};
+/** The frozen data contract between generated code and the runtime: one operation's wire shape. */
+export type OperationDescriptor = {
+    id: string;
+    method: string;
+    path: string;
+    tags?: readonly string[];
+    params?: readonly ParamSpec[];
+    /** `multipart: true` marks a typed object body serialized to FormData by the runtime. */
+    body?: {
+        contentType: string;
+        multipart?: boolean;
+    };
+    /** Defaults to `'json'` (content-type negotiation on parse). */
+    responseKind?: 'json' | 'text' | 'blob' | 'void' | 'sse';
+    sseDataKind?: 'json' | 'text';
+    /** OR-alternatives, each an AND-set: the runtime applies the first fully-configured one. */
+    security?: readonly (readonly SecuritySpec[])[];
+    pagination?: PaginationSpec;
+    /**
+     * `'grouped'` marks an operation that takes its inputs namespaced by layer even on a
+     * `argsStyle: 'flat'` client — the generator sets it where a merged call could not carry
+     * one name for two layers, and the operation's own input type says the same.
+     */
+    argsStyle?: 'grouped';
+    /**
+     * Declared success-response headers for throw-mode `{ envelope: true }`.
+     * `name` is the lowercased wire name; `key` is the camelCase envelope property.
+     */
+    responseHeaders?: readonly ResponseHeaderSpec[];
+};
+/** One declared response header the runtime coerces into the envelope `headers` object. */
+export type ResponseHeaderSpec = {
+    name: string;
+    key: string;
+    type: 'string' | 'number' | 'boolean';
+};
+/** A query value: scalars, arrays of scalars, or objects (serialized as deepObject brackets). */
+export type QueryValue = string | number | boolean | null | undefined | Array<string | number | boolean | null | undefined> | Record<string, unknown>;
+/** A credential: a literal, or a (possibly async) function resolved per request (refresh flows). */
+export type TokenProvider = string | (() => string | Promise<string>);
+/** Per-instance credentials, keyed by the scheme kinds the runtime can inject. */
+export type AuthCredentials = {
+    bearer?: TokenProvider;
+    basic?: {
+        username: string;
+        password: string;
+    };
+    apiKey?: Record<string, TokenProvider>;
+};
+/** Backoff shape: 'fixed' = constant delay; 'exponential' = doubling per attempt. */
+export type RetryStrategy = 'fixed' | 'exponential';
+/**
+ * The operation's identity, exposed to middleware for targeting (`ctx.operation`).
+ * Generated clients instantiate the type parameters with the spec's literal unions
+ * (`OperationId`/`OperationPath`/`OperationTag`) so a misspelled operation id in a
+ * middleware comparison fails to compile; the string defaults keep every
+ * spec-independent consumer (`runtime-contract.ts`, the runtime internals) working
+ * with the base shape. `tags` stays mutable (`Tag[]`) so setup-contract types
+ * (byte-locked to generated output) remain assignable through middleware callbacks.
+ */
+export type OperationContext<Id extends string = string, Path extends string = string, Tag extends string = string> = {
+    id: Id;
+    path: Path;
+    tags: Tag[];
+};
+/** The mutable request context threaded through the middleware chain. */
+export type RequestContext<Op extends OperationContext = OperationContext> = {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: unknown;
+    operation: Op;
+};
+/** The failed attempt handed to a custom `retryOn`: exactly one of `response`/`error` is set. */
+export type RetryContext<Op extends OperationContext = OperationContext> = {
+    attempt: number;
+    request: RequestContext<Op>;
+    response?: Response;
+    error?: unknown;
+};
+/** Opt-in retry policy; a per-call override merges field-by-field over the config policy. */
+export type RetryConfig<Op extends OperationContext = OperationContext> = {
+    retries?: number;
+    retryDelay?: number;
+    retryStrategy?: RetryStrategy;
+    jitter?: boolean;
+    retryOn?: (ctx: RetryContext<Op>) => boolean | Promise<boolean>;
+};
+/**
+ * Structural stand-in for the runtime's ApiError so this module stays import-free
+ * (pure types); the real `ApiError` class is assignable to it.
+ */
+export type ApiErrorLike = globalThis.Error & {
+    url: string;
+    status: number;
+    statusText: string;
+    body: unknown;
+};
+export type SettledCall = {
+    response?: Response;
+    error?: unknown;
+    attempts: number;
+    durationMs: number;
+};
+/** One interceptor: any subset of the four hooks. */
+export type Middleware<Op extends OperationContext = OperationContext> = {
+    onRequest?: (ctx: RequestContext<Op>) => void | Promise<void>;
+    onResponse?: (response: Response, ctx: RequestContext<Op>) => Response | void | Promise<Response | void>;
+    /** Throw mode only: may map/replace the error. */
+    onError?: (error: ApiErrorLike, ctx: RequestContext<Op>) => globalThis.Error | Promise<globalThis.Error>;
+    onSettled?: (ctx: RequestContext<Op>, call: SettledCall) => void | Promise<void>;
+};
+/** Client configuration: transport, defaults, retry policy, middleware, and credentials. */
+export type ClientConfig<Op extends OperationContext = OperationContext> = {
+    serverUrl?: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    retry?: RetryConfig<Op>;
+    /** Milliseconds before a request attempt aborts (covers the body read too; each retry
+     * attempt gets a fresh budget). Per-call `timeout` overrides it, `0` disables it.
+     * SSE streams are long-lived by design and never inherit this value. */
+    timeout?: number;
+    /** Send an `Idempotency-Key` header on POST/PATCH (one stable key per logical call,
+     * reused across retry attempts) — which also makes those retries safe under the
+     * default retry policy. `true` generates a UUID per call; a function supplies the key. */
+    idempotencyKey?: boolean | (() => string);
+    /** Identifies this client to the API via an `X-Redocly-Client` header (the generator
+     * bakes a default). Sent only OUTSIDE browsers — a custom header would force a CORS
+     * preflight. Override with your own value, or `false` to disable. */
+    clientHeader?: string | false;
+    middleware?: Middleware<Op>[];
+    auth?: AuthCredentials;
+    /** Fixed at generate time by the generator (`'throw'` when omitted); `configure()` ignores it. */
+    errorMode?: 'throw' | 'result';
+    /**
+     * How each call spells its inputs: `'grouped'` (the default) namespaces them by layer —
+     * `{ path, query, headers, cookies, body }` — and `'flat'` takes one merged object.
+     * Fixed at generate time, like `errorMode`, because it shapes the static types.
+     */
+    argsStyle?: 'grouped' | 'flat';
+    onRequest?: Middleware<Op>['onRequest'];
+    onResponse?: Middleware<Op>['onResponse'];
+    onError?: Middleware<Op>['onError'];
+};
+/** Response readers for the per-call `parseAs` override. */
+export type ParseAs = 'auto' | 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData' | 'stream';
+/** Per-call options: standard `RequestInit` plus a retry override, a timeout override
+ * (`0` disables the config default), and a forced reader. */
+export type RequestOptions = RequestInit & {
+    retry?: RetryConfig;
+    timeout?: number;
+    /** Per-call idempotency key: a literal key, `true` to generate one, `false` to skip. */
+    idempotencyKey?: string | boolean | (() => string);
+    parseAs?: ParseAs;
+    /**
+     * Throw mode only: return `{ data, headers, response }` instead of the parsed body;
+     * ignored in result mode. The explicit `| undefined` keeps the wrappers' emitted
+     * `envelope: undefined` strip legal under `exactOptionalPropertyTypes`.
+     */
+    envelope?: boolean | undefined;
+};
+/** Throw-mode success envelope when `RequestOptions.envelope` is `true`. */
+export type Envelope<TData, THeaders = Record<string, never>> = {
+    data: TData;
+    headers: THeaders;
+    response: Response;
+};
+/** Per-call options for an SSE stream; reconnect defaults to true. */
+export type SseOptions = RequestInit & {
+    reconnect?: boolean;
+    reconnectDelay?: number;
+};
+/** A single decoded Server-Sent Event with its payload typed from the spec. */
+export type ServerSentEvent<T> = {
+    event?: string;
+    data: T;
+    id?: string;
+    retry?: number;
+};
+/** Result-mode return shape: exactly one of `data`/`error` is set. */
+export type Result<TData, TError> = {
+    data: TData;
+    error: undefined;
+    response: Response;
+} | {
+    data: undefined;
+    error: TError;
+    response: Response;
+};
+/**
+ * The generated `Ops` type's shape: per-operation args/result, plus `kind: 'sse'` for
+ * streams and, for paginated operations, `item` (the page's element type) and — on
+ * result-mode clients only — `page` (the RAW page type `.pages()` yields, since
+ * iteration unwraps the `Result` envelope the one-shot `result` carries).
+ */
+export type OpsShape = Record<string, {
+    args: object;
+    result: unknown;
+    kind?: 'sse';
+    item?: unknown;
+    page?: unknown;
+    /** Declared success-response headers for `{ envelope: true }` (camelCase keys). */
+    headers?: object;
+    /** Result-mode entries ignore the throw-only `envelope` option. */
+    mode?: 'result';
+}>;
+/** The always-present client members (assigned after the operation loop — they win collisions). */
+export type ClientCore<Op extends OperationContext = OperationContext> = {
+    /** Merge into the config; note `middleware` REPLACES the chain (use `use()` to compose). */
+    configure(config: ClientConfig<Op>): void;
+    /** Append interceptors (composes with baked/publisher middleware). */
+    use(...middleware: Middleware<Op>[]): void;
+    auth: {
+        bearer(token: TokenProvider): void;
+        basic(username: string, password: string): void;
+        apiKey(scheme: string, value: TokenProvider): void;
+    };
+};
+/**
+ * The standard TypeScript optionality probe: `{}` has no required members, so
+ * `{} extends A` is true exactly when every member of `A` is optional.
+ */
+type NoRequiredKeys<A> = {} extends A ? true : false;
+/**
+ * The page type `.pages()` yields: the RAW page declared by `page` (the generator
+ * writes it only on result-mode paginated entries, whose `result` is the envelope),
+ * or the method's own `result` (throw mode — already the raw page).
+ */
+type PageOf<Entry extends OpsShape[string]> = Entry extends {
+    page: unknown;
+} ? Entry['page'] : Entry['result'];
+/**
+ * The auto-pagination members intersected onto a paginated method — present exactly when
+ * the Ops entry declares `item` (the generator writes it only for paginated operations).
+ * Args optionality mirrors the method's own; `unknown` otherwise (identity under `&`).
+ * Iteration is error-mode-agnostic: `.pages()`/`.items()` yield raw pages/items, and a
+ * failed page aborts iteration by throwing `ApiError`, even on result-mode clients; the
+ * `onError` middleware hook (throw-mode-only) is not invoked.
+ */
+type Paginated<Entry extends OpsShape[string]> = 'item' extends keyof Entry ? NoRequiredKeys<Entry['args']> extends true ? {
+    pages(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;
+    items(args?: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;
+} : {
+    pages(args: Entry['args'], init?: RequestOptions): AsyncGenerator<PageOf<Entry>>;
+    items(args: Entry['args'], init?: RequestOptions): AsyncGenerator<Entry['item']>;
+} : unknown;
+/**
+ * The stable identity every client method carries: the SPEC operationId (also set as
+ * `fn.name`, but `operationId` is the explicit, minification-proof form) — a robust
+ * cache key for consumer wrappers (react-query keys and the like).
+ */
+export type OperationMethodIdentity = {
+    readonly operationId: string;
+};
+/** Declared response-header bag for an Ops entry; empty object when none are declared. */
+type HeadersOf<Entry extends OpsShape[string]> = 'headers' extends keyof Entry ? NonNullable<Entry['headers']> : Record<string, never>;
+/**
+ * Return type of a throw-mode call: the body by default, `Envelope<…>` for a literal
+ * `envelope: true`, their union when the flag is a widened `boolean`. Exact
+ * `RequestOptions` stays the body — pre-envelope package-mode flat sugar typed every
+ * `init` parameter as `RequestOptions`, and widening that would break upgrades without
+ * a regenerate. The `keyof` presence gate keeps `{ headers }` / `{ signal }` as the body
+ * (`TInit['envelope']` through `TInit & RequestOptions` would otherwise be
+ * `boolean | undefined`).
+ */
+export type EnvelopeResult<TData, THeaders, TInit extends RequestOptions | undefined> = TInit extends undefined ? TData : RequestOptions extends TInit ? TInit extends RequestOptions ? TData : EnvelopeResultForKnownInit<TData, THeaders, TInit> : EnvelopeResultForKnownInit<TData, THeaders, TInit>;
+type EnvelopeResultForKnownInit<TData, THeaders, TInit> = 'envelope' extends keyof TInit ? [TInit['envelope' & keyof TInit]] extends [true] ? Envelope<TData, THeaders> : [TInit['envelope' & keyof TInit]] extends [false | undefined] ? TData : TData | Envelope<TData, THeaders> : TData;
+/** A one-shot method whose return shape never varies with per-call options. */
+type BodyMethod<Entry extends OpsShape[string]> = NoRequiredKeys<Entry['args']> extends true ? (args?: Entry['args'], init?: RequestOptions) => Promise<Entry['result']> : (args: Entry['args'], init?: RequestOptions) => Promise<Entry['result']>;
+/**
+ * One-shot (non-SSE) method: default returns the body; `{ envelope: true }` returns
+ * `{ data, headers, response }` with typed declared headers.
+ */
+type ThrowMethod<Entry extends OpsShape[string]> = NoRequiredKeys<Entry['args']> extends true ? <Init extends RequestOptions | undefined = undefined>(args?: Entry['args'], init?: Init) => Promise<EnvelopeResult<Entry['result'], HeadersOf<Entry>, Init>> : <Init extends RequestOptions | undefined = undefined>(args: Entry['args'], init?: Init) => Promise<EnvelopeResult<Entry['result'], HeadersOf<Entry>, Init>>;
+/** The typed instance client: one bound method per operation plus the core members. */
+export type Client<Ops extends OpsShape, Op extends OperationContext = OperationContext> = {
+    [K in keyof Ops]: Ops[K] extends {
+        kind: 'sse';
+    } ? (NoRequiredKeys<Ops[K]['args']> extends true ? (args?: Ops[K]['args'], init?: SseOptions) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>> : (args: Ops[K]['args'], init?: SseOptions) => AsyncGenerator<ServerSentEvent<Ops[K]['result']>>) & OperationMethodIdentity : (Ops[K] extends {
+        mode: 'result';
+    } ? BodyMethod<Ops[K]> : ThrowMethod<Ops[K]>) & OperationMethodIdentity & Paginated<Ops[K]>;
+} & ClientCore<Op>;
+export {};

package/dist/runtime/url.d.ts

@@ -0,0 +1,24 @@
+import { ParamSpec, QueryValue } from './types.ts';
+/**
+ * The RESOLVED OpenAPI serialization spec for one query parameter — callers apply the
+ * OpenAPI defaults (`style: 'form'`, `explode: true`) before building one.
+ */
+export type QueryStyle = {
+    style: NonNullable<ParamSpec['style']>;
+    explode: boolean;
+    allowReserved?: boolean;
+};
+/**
+ * Encode everything except the RFC-3986 reserved set, for `allowReserved: true` params —
+ * `filter=a/b` survives instead of `filter=a%2Fb`.
+ */
+export declare function encodeReserved(value: string): string;
+/** Substitute `{name}` template segments with encoded values; a missing value is a caller bug. */
+export declare function substitutePath(template: string, values: Record<string, unknown>): string;
+/**
+ * Build the request URL: `serverUrl` (trailing slash trimmed) + path + serialized query.
+ * Query parameters honor their OpenAPI `style`/`explode`/`allowReserved` (from `styles`);
+ * without a spec, arrays repeat the key (`form`+`explode`), objects serialize as
+ * `deepObject` brackets, and `null`/`undefined` entries are skipped.
+ */
+export declare function buildUrl(serverUrl: string, path: string, query?: Record<string, QueryValue>, styles?: Record<string, QueryStyle>): string;

package/dist/runtime/url.js

@@ -0,0 +1,62 @@
+//#region src/runtime/url.ts
+/**
+* Encode everything except the RFC-3986 reserved set, for `allowReserved: true` params —
+* `filter=a/b` survives instead of `filter=a%2Fb`.
+*/
+function encodeReserved(value) {
+	return encodeURIComponent(value).replace(/%(3A|2F|3F|23|5B|5D|40|21|24|26|27|28|29|2A|2B|2C|3B|3D)/g, (match) => decodeURIComponent(match));
+}
+/** Substitute `{name}` template segments with encoded values; a missing value is a caller bug. */
+function substitutePath(template, values) {
+	return template.replace(/\{([^{}]+)\}/g, (_match, name) => {
+		const value = values[name];
+		if (value === void 0) throw new Error(`Missing path parameter "${name}"`);
+		return encodeURIComponent(String(value));
+	});
+}
+/**
+* Build the request URL: `serverUrl` (trailing slash trimmed) + path + serialized query.
+* Query parameters honor their OpenAPI `style`/`explode`/`allowReserved` (from `styles`);
+* without a spec, arrays repeat the key (`form`+`explode`), objects serialize as
+* `deepObject` brackets, and `null`/`undefined` entries are skipped.
+*/
+function buildUrl(serverUrl, path, query, styles) {
+	let end = serverUrl.length;
+	while (end > 0 && serverUrl.charCodeAt(end - 1) === 47) end--;
+	const url = serverUrl.slice(0, end) + path;
+	if (!query) return url;
+	const params = new URLSearchParams();
+	const raw = [];
+	for (const [key, value] of Object.entries(query)) {
+		if (value === void 0 || value === null) continue;
+		const spec = styles?.[key];
+		if (!spec) {
+			if (Array.isArray(value)) {
+				for (const v of value) if (v !== void 0 && v !== null) params.append(key, String(v));
+			} else if (Object(value) === value) {
+				for (const [subKey, subValue] of Object.entries(value)) if (subValue !== void 0 && subValue !== null) params.append(`${key}[${subKey}]`, String(subValue));
+			} else params.append(key, String(value));
+			continue;
+		}
+		if (Array.isArray(value)) {
+			const items = value.filter((v) => v !== void 0 && v !== null).map(String);
+			if (spec.style === "form" && spec.explode) for (const v of items) if (spec.allowReserved) raw.push(`${key}=${encodeReserved(v)}`);
+			else params.append(key, v);
+			else {
+				const delim = spec.style === "pipeDelimited" ? "|" : spec.style === "spaceDelimited" ? "%20" : ",";
+				const enc = spec.allowReserved ? encodeReserved : encodeURIComponent;
+				raw.push(`${encodeURIComponent(key)}=${items.map(enc).join(delim)}`);
+			}
+		} else if (Object(value) === value) {
+			for (const [subKey, subValue] of Object.entries(value)) if (subValue !== void 0 && subValue !== null) {
+				if (spec.allowReserved) raw.push(`${key}[${subKey}]=${encodeReserved(String(subValue))}`);
+				else params.append(`${key}[${subKey}]`, String(subValue));
+			}
+		} else if (spec.allowReserved) raw.push(`${key}=${encodeReserved(String(value))}`);
+		else params.append(key, String(value));
+	}
+	const qs = [params.toString(), ...raw].filter(Boolean).join("&");
+	return qs ? `${url}?${qs}` : url;
+}
+//#endregion
+export { buildUrl, encodeReserved, substitutePath };