skilld-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,97 @@
+import { OperationInput, OperationOutput, SkilldV1ErrorCode, SkilldV1OperationDefinition, SkilldV1Problem, SkilldV1Protocol, SkilldV1ProtocolLike, skilldV1Protocol } from "./contract.mjs";
+//#region src/client.d.ts
+type Result<TValue, TError> = {
+  _tag: 'Ok';
+  value: TValue;
+  requestId?: string;
+} | {
+  _tag: 'Err';
+  error: TError;
+};
+/** The input failed the operation's schema, so nothing was sent. */
+interface RequestFailure {
+  _tag: 'RequestFailure';
+  operationId: string;
+  location: 'input' | 'params' | 'query' | 'body';
+  issues: readonly unknown[];
+}
+/** skilld.dev answered with a problem the contract declares. */
+interface ApiFailure {
+  _tag: 'ApiFailure';
+  operationId: string;
+  code: SkilldV1ErrorCode;
+  status: number;
+  title: string;
+  detail?: string;
+  requestId?: string;
+  retryable: boolean;
+  problem: SkilldV1Problem;
+}
+/** skilld.dev answered with something the contract does not allow. Report it with the request ID. */
+interface ContractFailure {
+  _tag: 'ContractFailure';
+  operationId: string;
+  status: number;
+  message: string;
+  issues: readonly unknown[];
+  requestId?: string;
+}
+/** The request never got an answer. */
+interface TransportFailure {
+  _tag: 'TransportFailure';
+  operationId: string;
+  reason: 'aborted' | 'credential' | 'network';
+  message: string;
+  retryable: boolean;
+  cause?: unknown;
+}
+type SkilldFailure = RequestFailure | ApiFailure | ContractFailure | TransportFailure;
+type FetchImplementation = (input: string, init: RequestInit) => Promise<Response>;
+type TokenResolver = string | (() => string | undefined | Promise<string | undefined>);
+interface RetryOptions {
+  /** Attempts per call, the first one included. Default 3. */
+  maxAttempts?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+}
+interface CreateSkilldClientOptions {
+  /** Default `https://skilld.dev`. */
+  baseUrl?: string;
+  /**
+   * A skilld token: `skilld auth login` stores one, and skilld.dev/me/cli-tokens/new
+   * creates one. Only account operations need it.
+   */
+  token?: TokenResolver;
+  fetch?: FetchImplementation;
+  headers?: HeadersInit;
+  /** Send the skilld.dev sign-in cookie. For a page served from skilld.dev only. */
+  credentials?: RequestCredentials;
+  retry?: RetryOptions;
+}
+interface CallOptions {
+  signal?: AbortSignal;
+}
+/** Calls whose input has no required location take the input as optional. */
+type EmptyInput = Record<never, never>;
+type OperationCall<TOperation extends SkilldV1OperationDefinition> = EmptyInput extends OperationInput<TOperation> ? (input?: OperationInput<TOperation>, options?: CallOptions) => Promise<Result<OperationOutput<TOperation>, SkilldFailure>> : (input: OperationInput<TOperation>, options?: CallOptions) => Promise<Result<OperationOutput<TOperation>, SkilldFailure>>;
+type DomainClient<TOperations extends Readonly<Record<string, SkilldV1OperationDefinition>>> = { [TKey in keyof TOperations]: OperationCall<TOperations[TKey]>; };
+type ProtocolClient<TProtocol extends SkilldV1ProtocolLike> = { [TName in keyof TProtocol['registries']]: DomainClient<TProtocol['registries'][TName]['operations']>; } & {
+  execute: <const TOperation extends SkilldV1OperationDefinition>(operation: TOperation, input?: OperationInput<TOperation>, options?: CallOptions) => Promise<Result<OperationOutput<TOperation>, SkilldFailure>>;
+};
+type SkilldClient = ProtocolClient<SkilldV1Protocol>;
+/**
+ * A typed client for the skilld API. Every call answers a `Result`: check
+ * `_tag` before you read `value`. Nothing throws for an expected failure.
+ *
+ * ```ts
+ * const skilld = createSkilldClient({ token: process.env.SKILLD_TOKEN })
+ * const found = await skilld.skills.search({ query: { q: 'tailwind' } })
+ * if (found._tag === 'Err')
+ *   throw new Error(found.error._tag)
+ * ```
+ */
+declare function createSkilldClient(options?: CreateSkilldClientOptions): SkilldClient;
+declare function createProtocolClient<const TProtocol extends SkilldV1ProtocolLike>(protocol: TProtocol, options?: CreateSkilldClientOptions): ProtocolClient<TProtocol>;
+//#endregion
+export { ApiFailure, CallOptions, ContractFailure, CreateSkilldClientOptions, DomainClient, FetchImplementation, OperationCall, type OperationInput, type OperationOutput, ProtocolClient, RequestFailure, Result, RetryOptions, SkilldClient, SkilldFailure, type SkilldV1ErrorCode, type SkilldV1OperationDefinition, type SkilldV1Problem, type SkilldV1Protocol, TokenResolver, TransportFailure, createProtocolClient, createSkilldClient, skilldV1Protocol };

package/dist/index.mjs

@@ -0,0 +1,253 @@
+import { SKILLD_V1_ERROR_STATUS, SKILLD_V1_IMPLICIT_ERRORS, SKILLD_V1_RESPONSE_HEADERS, SKILLD_V1_RETRYABLE_ERRORS, buildOperationPath, listOperations, problemSchema, skilldV1Protocol } from "./contract.mjs";
+//#region src/client.ts
+function err(error) {
+	return {
+		_tag: "Err",
+		error
+	};
+}
+function defaultSleep(milliseconds, signal) {
+	if (signal?.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		const handle = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, milliseconds);
+		function onAbort() {
+			clearTimeout(handle);
+			reject(signal?.reason);
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+function resolveRetry(options) {
+	const maxAttempts = options?.maxAttempts ?? 3;
+	const baseDelayMs = options?.baseDelayMs ?? 200;
+	const maxDelayMs = options?.maxDelayMs ?? 5e3;
+	if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 10) throw new TypeError("retry.maxAttempts must be an integer from 1 to 10.");
+	if (baseDelayMs < 0 || maxDelayMs < baseDelayMs) throw new TypeError("retry delays must be nonnegative, and maxDelayMs must be at least baseDelayMs.");
+	return {
+		maxAttempts,
+		baseDelayMs,
+		maxDelayMs,
+		sleep: options?.sleep ?? defaultSleep
+	};
+}
+function retryDelay(attempt, retryAfter, retry) {
+	const exponential = Math.min(retry.maxDelayMs, retry.baseDelayMs * 2 ** (attempt - 1));
+	const seconds = retryAfter === null ? NaN : Number(retryAfter);
+	const requested = Number.isFinite(seconds) && seconds >= 0 ? Math.ceil(seconds * 1e3) : 0;
+	return Math.min(Math.max(exponential, requested), 6e4);
+}
+function appendQuery(path, query) {
+	if (!query) return path;
+	const search = new URLSearchParams();
+	for (const key of Object.keys(query).sort()) {
+		const value = query[key];
+		if (value === void 0 || value === null) continue;
+		for (const item of Array.isArray(value) ? value : [value]) search.append(key, String(item));
+	}
+	const serialized = search.toString();
+	return serialized ? `${path}?${serialized}` : path;
+}
+function prepare(operation, input) {
+	const source = input ?? {};
+	if (typeof source !== "object" || Array.isArray(source)) return err({
+		_tag: "RequestFailure",
+		operationId: operation.id,
+		location: "input",
+		issues: ["input must be an object"]
+	});
+	const extra = Object.keys(source).filter((key) => key !== "params" && key !== "query" && key !== "body");
+	if (extra.length > 0) return err({
+		_tag: "RequestFailure",
+		operationId: operation.id,
+		location: "input",
+		issues: [`unknown input keys: ${extra.join(", ")}`]
+	});
+	const parsed = {};
+	for (const location of [
+		"params",
+		"query",
+		"body"
+	]) {
+		const schema = operation.request[location];
+		const supplied = source[location] !== void 0;
+		if (!schema) {
+			if (supplied) return err({
+				_tag: "RequestFailure",
+				operationId: operation.id,
+				location,
+				issues: [`${operation.id} takes no ${location}`]
+			});
+			continue;
+		}
+		const result = schema.safeParse(supplied ? source[location] : location === "body" ? void 0 : {});
+		if (!result.success) return err({
+			_tag: "RequestFailure",
+			operationId: operation.id,
+			location,
+			issues: result.error.issues
+		});
+		parsed[location] = result.data;
+	}
+	return {
+		_tag: "Ok",
+		path: appendQuery(buildOperationPath(operation, parsed.params), parsed.query),
+		body: parsed.body === void 0 ? void 0 : JSON.stringify(parsed.body)
+	};
+}
+async function readJson(response) {
+	const text = await response.text();
+	if (!text) return {
+		_tag: "Ok",
+		value: null
+	};
+	return Promise.resolve().then(() => ({
+		_tag: "Ok",
+		value: JSON.parse(text)
+	})).catch((cause) => ({
+		_tag: "Err",
+		cause
+	}));
+}
+async function resolveToken(token) {
+	return (typeof token === "function" ? await token() : token)?.trim() || void 0;
+}
+/**
+* A typed client for the skilld API. Every call answers a `Result`: check
+* `_tag` before you read `value`. Nothing throws for an expected failure.
+*
+* ```ts
+* const skilld = createSkilldClient({ token: process.env.SKILLD_TOKEN })
+* const found = await skilld.skills.search({ query: { q: 'tailwind' } })
+* if (found._tag === 'Err')
+*   throw new Error(found.error._tag)
+* ```
+*/
+function createSkilldClient(options = {}) {
+	return createProtocolClient(skilldV1Protocol, options);
+}
+function createProtocolClient(protocol, options = {}) {
+	const retry = resolveRetry(options.retry);
+	const baseUrl = (options.baseUrl ?? "https://skilld.dev").replace(/\/+$/, "");
+	const fetchImplementation = options.fetch ?? globalThis.fetch?.bind(globalThis);
+	if (typeof fetchImplementation !== "function") throw new TypeError("createSkilldClient needs a fetch implementation in this runtime.");
+	const registered = new Map(listOperations(protocol).map(({ operation }) => [operation.id, operation]));
+	async function execute(operation, input, callOptions = {}) {
+		const known = registered.get(operation.id);
+		if (!known || known.method !== operation.method || known.path !== operation.path) return err({
+			_tag: "RequestFailure",
+			operationId: operation.id,
+			location: "input",
+			issues: [`${operation.id} is not part of this client's protocol`]
+		});
+		const prepared = prepare(operation, input);
+		if (prepared._tag === "Err") return prepared;
+		const canRetry = operation.semantics.kind === "query" || operation.semantics.retry === "idempotent";
+		const declared = /* @__PURE__ */ new Set([...operation.errors, ...SKILLD_V1_IMPLICIT_ERRORS]);
+		for (let attempt = 1;; attempt++) {
+			const headers = new Headers(options.headers);
+			headers.set("accept", "application/json");
+			if (prepared.body !== void 0) headers.set("content-type", "application/json");
+			const token = await Promise.resolve(options.token).then(resolveToken).then((value) => ({
+				_tag: "Ok",
+				value
+			}), (cause) => ({
+				_tag: "Err",
+				cause
+			}));
+			if (token._tag === "Err") return err({
+				_tag: "TransportFailure",
+				operationId: operation.id,
+				reason: "credential",
+				message: "Could not resolve the skilld token.",
+				retryable: false,
+				cause: token.cause
+			});
+			if (token.value) headers.set("authorization", `Bearer ${token.value}`);
+			const sent = await fetchImplementation(`${baseUrl}${prepared.path}`, {
+				method: operation.method,
+				headers,
+				body: prepared.body,
+				signal: callOptions.signal,
+				credentials: options.credentials
+			}).then((response) => ({
+				_tag: "Ok",
+				response
+			}), (cause) => ({
+				_tag: "Err",
+				cause
+			}));
+			if (sent._tag === "Err") {
+				const aborted = callOptions.signal?.aborted === true;
+				if (!aborted && canRetry && attempt < retry.maxAttempts) {
+					if (await retry.sleep(retryDelay(attempt, null, retry), callOptions.signal).then(() => true, () => false)) continue;
+				}
+				return err({
+					_tag: "TransportFailure",
+					operationId: operation.id,
+					reason: aborted ? "aborted" : "network",
+					message: `${operation.id}: ${aborted ? "request aborted" : "network request failed"}`,
+					retryable: !aborted && canRetry,
+					cause: sent.cause
+				});
+			}
+			const response = sent.response;
+			const requestId = response.headers.get(SKILLD_V1_RESPONSE_HEADERS.requestId) ?? void 0;
+			const contractFailure = (message, issues = []) => err({
+				_tag: "ContractFailure",
+				operationId: operation.id,
+				status: response.status,
+				message,
+				issues,
+				requestId
+			});
+			if (response.status === operation.response.status) {
+				const body = operation.response.body;
+				if (body === null) {
+					await response.body?.cancel();
+					return {
+						_tag: "Ok",
+						value: null,
+						requestId
+					};
+				}
+				const payload = await readJson(response);
+				if (payload._tag === "Err") return contractFailure(`${operation.id}: the answer was not JSON`, [payload.cause]);
+				const parsed = body.client.safeParse(payload.value);
+				return parsed.success ? {
+					_tag: "Ok",
+					value: parsed.data,
+					requestId
+				} : contractFailure(`${operation.id}: the answer broke its schema`, parsed.error.issues);
+			}
+			if (response.ok) return contractFailure(`${operation.id}: undeclared success status ${response.status}`);
+			const payload = await readJson(response);
+			const problem = payload._tag === "Ok" ? problemSchema.client.safeParse(payload.value) : null;
+			if (!problem?.success) return contractFailure(`${operation.id}: status ${response.status} without a problem body`);
+			const { code } = problem.data;
+			if (!declared.has(code) || SKILLD_V1_ERROR_STATUS[code] !== response.status) return contractFailure(`${operation.id}: undeclared problem ${code} with status ${response.status}`);
+			const failure = {
+				_tag: "ApiFailure",
+				operationId: operation.id,
+				code,
+				status: response.status,
+				title: problem.data.title,
+				detail: problem.data.detail,
+				requestId,
+				retryable: canRetry && SKILLD_V1_RETRYABLE_ERRORS.has(code),
+				problem: problem.data
+			};
+			if (failure.retryable && attempt < retry.maxAttempts) {
+				if (await retry.sleep(retryDelay(attempt, response.headers.get(SKILLD_V1_RESPONSE_HEADERS.retryAfter), retry), callOptions.signal).then(() => true, () => false)) continue;
+			}
+			return err(failure);
+		}
+	}
+	const client = { execute };
+	for (const [name, registry] of Object.entries(protocol.registries)) client[name] = Object.fromEntries(Object.entries(registry.operations).map(([key, operation]) => [key, (input, callOptions) => execute(operation, input, callOptions)]));
+	return client;
+}
+//#endregion
+export { createProtocolClient, createSkilldClient, skilldV1Protocol };