@talqing/sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,189 @@
+/** The hand-written half of the SDK: everything the OpenAPI document cannot say.
+ *
+ * The API surface itself is generated into `./gen` from `openapi/openapi.json`
+ * and is never edited here. What is left is the client object that carries
+ * credentials, the error type, the two browser-redirect URLs that are
+ * deliberately absent from the document, and a pagination helper.
+ */
+
+import { TalqingApi } from "./gen/index.js";
+import { createClient, createConfig } from "./gen/client/index.js";
+import type { Client } from "./gen/client/index.js";
+import type { ErrorResponse } from "./gen/types.gen.js";
+
+/* Free-form JSON: userdata, tool arguments, `vars`, a tool's JSON Schema.
+ *
+ * `JsonObject` is exactly what the document says such a field is — an object of
+ * `unknown` — so a value read off a response drops straight into it. Naming it
+ * anything narrower would be the SDK asserting a guarantee the API does not
+ * make, and every read would then need a cast to get back to the truth.
+ *
+ * `JsonValue` is the recursive form, for a payload the CALLER builds: there it
+ * is a real constraint, because it refuses a `Date` or a class instance that
+ * would not survive `JSON.stringify`. */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export type JsonObject = { [key: string]: unknown };
+
+type Awaitable<T> = T | Promise<T>;
+type TokenProvider = string | (() => Awaitable<string | null | undefined>);
+
+/** A page of results. The document spells each instantiation out by hand
+ *  (`PageAgentResponse`) because OpenAPI has no generics; TypeScript is
+ *  structural, so those satisfy this and generic helpers still work. */
+export interface Page<T> {
+  items: T[];
+  has_more: boolean;
+  limit: number;
+  offset: number;
+}
+
+/**
+ * Every generated method, with the `| undefined` that `throwOnError` makes
+ * impossible removed.
+ *
+ * The generator emits `<ThrowOnError extends boolean = false>` on every method,
+ * so a client configured to throw still returns `T | undefined` at the type
+ * level and every call site would need a `!`. There is no setting for it. This
+ * re-types the whole tree once instead.
+ *
+ * `Exclude<R, undefined>` rather than `NonNullable<R>`: the latter turns the
+ * `void` of a 204 into `{}`. `...args: infer A` rather than named parameters:
+ * it keeps each method's optional-argument arity, so `agents.list()` with no
+ * argument still compiles.
+ */
+type Throwing<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => Promise<infer R>
+    ? (...args: A) => Promise<Exclude<R, undefined>>
+    : Throwing<T[K]>;
+};
+
+/** Every error this API returns, in the one shape it returns them in. */
+export class TalqingApiError extends Error {
+  readonly name = "TalqingApiError";
+  readonly status: number;
+  /** Per-field problems, when the failure had more than one. Always present. */
+  readonly errors: string[];
+  readonly response: Response;
+
+  constructor(body: ErrorResponse, response: Response) {
+    super(body.detail.message);
+    this.status = response.status;
+    this.errors = body.detail.errors;
+    this.response = response;
+  }
+}
+
+export interface TalqingClientOptions {
+  /** Base URL of the Talqing API, e.g. `https://api.example.com`. Required,
+   *  with no default: a bundler inlines this at build time, so a localhost
+   *  fallback would silently ship a production bundle calling nothing. */
+  baseUrl: string;
+  /** A personal access token, or a function returning one. Server-side use. */
+  token?: TokenProvider;
+  /** `"include"` for the dashboard's cookie session. */
+  credentials?: RequestCredentials;
+  headers?: Record<string, string>;
+  fetch?: typeof fetch;
+  /**
+   * Called when the API answers 401. The credentials are gone, so every other
+   * call will fail identically — this is a session-level fact, not a per-call
+   * one, and handling it here keeps every caller from re-deriving it. The error
+   * is still thrown afterwards.
+   */
+  onUnauthorized?: (error: TalqingApiError) => void;
+}
+
+interface TalqingClientExtras {
+  readonly baseUrl: string;
+  /** The underlying transport, for interceptors and one-off requests. */
+  readonly http: Client;
+  /** Where to send the browser to start Google sign-in. */
+  googleLoginUrl(): string;
+  /** Where to send the browser to authorize an integration. */
+  oauthStartUrl(provider: string, integrationId?: string): string;
+}
+
+export interface TalqingClient extends Throwing<TalqingApi>, TalqingClientExtras {}
+
+class TalqingClientImpl extends TalqingApi implements TalqingClientExtras {
+  readonly baseUrl: string;
+  readonly http: Client;
+
+  constructor(options: TalqingClientOptions) {
+    // Types do not reach a JavaScript caller, or a value that is `string` but empty.
+    if (!options?.baseUrl?.trim()) {
+      throw new Error("TalqingClient requires a baseUrl (e.g. https://api.in.talqing.com)");
+    }
+    const baseUrl = options.baseUrl.replace(/\/+$/, "");
+    const http = createClient(
+      createConfig({
+        baseUrl,
+        throwOnError: true,
+        responseStyle: "data",
+        credentials: options.credentials,
+        headers: options.headers,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+        ...(options.token ? { auth: () => resolveToken(options.token) } : {}),
+      }),
+    );
+
+    // The transport throws the parsed error body — a plain object with no
+    // status and no stack. Replacing it here is what makes `catch (e)` see a
+    // real Error everywhere, including inside the generated methods.
+    http.interceptors.error.use((error, response) => {
+      // No response means the request never completed — a DNS failure, an
+      // abort, an offline tab. There is no status to carry, so the transport's
+      // own error is already the truthful one.
+      if (!response) return error;
+      const failure = new TalqingApiError(error as ErrorResponse, response);
+      if (failure.status === 401) options.onUnauthorized?.(failure);
+      return failure;
+    });
+
+    super({ client: http });
+    this.baseUrl = baseUrl;
+    this.http = http;
+  }
+
+  googleLoginUrl(): string {
+    return `${this.baseUrl}/v1/auth/google/start`;
+  }
+
+  oauthStartUrl(provider: string, integrationId?: string): string {
+    const url = new URL(`${this.baseUrl}/v1/integrations/oauth/${encodeURIComponent(provider)}/start`);
+    if (integrationId) url.searchParams.set("integration_id", integrationId);
+    return url.toString();
+  }
+}
+
+/* `Throwing` is a type-level narrowing of the same object — the runtime value
+ * is the generated class, unchanged — so the constructor is re-typed rather
+ * than the 155 methods being re-declared. */
+export const TalqingClient = TalqingClientImpl as unknown as new (
+  options: TalqingClientOptions,
+) => TalqingClient;
+
+async function resolveToken(token: TokenProvider | undefined): Promise<string | undefined> {
+  const value = typeof token === "function" ? await token() : token;
+  return value ?? undefined;
+}
+
+/**
+ * Walk every page of a list endpoint.
+ *
+ *     for await (const agent of paginate((q) => talqing.agents.list(q))) { … }
+ *
+ * Replaces the one-off `listAllAgents` the previous client carried: the page
+ * shape is the same on all 28 list endpoints, so the helper is too.
+ */
+export async function* paginate<T>(
+  page: (query: { limit: number; offset: number }) => Promise<Page<T>>,
+  { limit = 200 }: { limit?: number } = {},
+): AsyncGenerator<T> {
+  for (let offset = 0; ; offset += limit) {
+    const result = await page({ limit, offset });
+    yield* result.items;
+    if (!result.has_more) return;
+  }
+}

package/src/gen/apiVersion.ts

@@ -0,0 +1,4 @@
+// This file is auto-generated by scripts/api-version.mjs
+
+/** The Talqing API version `src/gen` was generated against. */
+export const API_VERSION = "1.0.0";

package/src/gen/client/client.gen.ts

@@ -0,0 +1,277 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+import { createSseClient } from '../core/serverSentEvents.gen.js';
+import type { HttpMethod } from '../core/types.gen.js';
+import { getValidRequestBody } from '../core/utils.gen.js';
+import type { Client, Config, RequestOptions, ResolvedRequestOptions } from './types.gen.js';
+import {
+  buildUrl,
+  createConfig,
+  createInterceptors,
+  getParseAs,
+  mergeConfigs,
+  mergeHeaders,
+  setAuthParams,
+} from './utils.gen.js';
+
+type ReqInit = Omit<RequestInit, 'body' | 'headers'> & {
+  body?: any;
+  headers: ReturnType<typeof mergeHeaders>;
+};
+
+export const createClient = (config: Config = {}): Client => {
+  let _config = mergeConfigs(createConfig(), config);
+
+  const getConfig = (): Config => ({ ..._config });
+
+  const setConfig = (config: Config): Config => {
+    _config = mergeConfigs(_config, config);
+    return getConfig();
+  };
+
+  const interceptors = createInterceptors<Request, Response, unknown, ResolvedRequestOptions>();
+
+  const beforeRequest = async <
+    TData = unknown,
+    TResponseStyle extends 'data' | 'fields' = 'fields',
+    ThrowOnError extends boolean = boolean,
+    Url extends string = string,
+  >(
+    options: RequestOptions<TData, TResponseStyle, ThrowOnError, Url>,
+  ) => {
+    const opts = {
+      ..._config,
+      ...options,
+      fetch: options.fetch ?? _config.fetch ?? globalThis.fetch,
+      headers: mergeHeaders(_config.headers, options.headers),
+      serializedBody: undefined as string | undefined,
+    };
+
+    if (opts.security) {
+      await setAuthParams(opts);
+    }
+
+    if (opts.requestValidator) {
+      await opts.requestValidator(opts);
+    }
+
+    if (opts.body !== undefined && opts.bodySerializer) {
+      opts.serializedBody = opts.bodySerializer(opts.body) as string | undefined;
+    }
+
+    // remove Content-Type header if body is empty to avoid sending invalid requests
+    if (opts.body === undefined || opts.serializedBody === '') {
+      opts.headers.delete('Content-Type');
+    }
+
+    const resolvedOpts = opts as typeof opts &
+      ResolvedRequestOptions<TResponseStyle, ThrowOnError, Url>;
+    const url = buildUrl(resolvedOpts);
+
+    return { opts: resolvedOpts, url };
+  };
+
+  const request: Client['request'] = async (options) => {
+    const throwOnError = options.throwOnError ?? _config.throwOnError;
+    const responseStyle = options.responseStyle ?? _config.responseStyle;
+
+    let request: Request | undefined;
+    let response: Response | undefined;
+
+    try {
+      const { opts, url } = await beforeRequest(options);
+      const requestInit: ReqInit = {
+        redirect: 'follow',
+        ...opts,
+        body: getValidRequestBody(opts),
+      };
+
+      request = new Request(url, requestInit);
+
+      for (const fn of interceptors.request.fns) {
+        if (fn) {
+          request = await fn(request, opts);
+        }
+      }
+
+      // fetch must be assigned here, otherwise it would throw the error:
+      // TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
+      const _fetch = opts.fetch!;
+
+      response = await _fetch(request);
+
+      for (const fn of interceptors.response.fns) {
+        if (fn) {
+          response = await fn(response, request, opts);
+        }
+      }
+
+      const result = {
+        request,
+        response,
+      };
+
+      if (response.ok) {
+        const parseAs =
+          (opts.parseAs === 'auto'
+            ? getParseAs(response.headers.get('Content-Type'))
+            : opts.parseAs) ?? 'json';
+
+        if (response.status === 204 || response.headers.get('Content-Length') === '0') {
+          let emptyData: any;
+          switch (parseAs) {
+            case 'arrayBuffer':
+            case 'blob':
+            case 'text':
+              emptyData = await response[parseAs]();
+              break;
+            case 'formData':
+              emptyData = new FormData();
+              break;
+            case 'stream':
+              emptyData = response.body;
+              break;
+            case 'json':
+            default:
+              emptyData = {};
+              break;
+          }
+          return opts.responseStyle === 'data'
+            ? emptyData
+            : {
+                data: emptyData,
+                ...result,
+              };
+        }
+
+        let data: any;
+        switch (parseAs) {
+          case 'arrayBuffer':
+          case 'blob':
+          case 'formData':
+          case 'text':
+            data = await response[parseAs]();
+            break;
+          case 'json': {
+            // Some servers return 200 with no Content-Length and empty body.
+            // response.json() would throw; read as text and parse if non-empty.
+            const text = await response.text();
+            data = text ? JSON.parse(text) : {};
+            break;
+          }
+          case 'stream':
+            return opts.responseStyle === 'data'
+              ? response.body
+              : {
+                  data: response.body,
+                  ...result,
+                };
+        }
+
+        if (parseAs === 'json') {
+          if (opts.responseValidator) {
+            await opts.responseValidator(data);
+          }
+
+          if (opts.responseTransformer) {
+            data = await opts.responseTransformer(data);
+          }
+        }
+
+        return opts.responseStyle === 'data'
+          ? data
+          : {
+              data,
+              ...result,
+            };
+      }
+
+      const textError = await response.text();
+      let jsonError: unknown;
+
+      try {
+        jsonError = JSON.parse(textError);
+      } catch {
+        // noop
+      }
+
+      throw jsonError ?? textError;
+    } catch (error) {
+      let finalError = error;
+
+      for (const fn of interceptors.error.fns) {
+        if (fn) {
+          finalError = await fn(finalError, response, request, options as ResolvedRequestOptions);
+        }
+      }
+
+      finalError = finalError || {};
+
+      if (throwOnError) {
+        throw finalError;
+      }
+
+      // TODO: we probably want to return error and improve types
+      return responseStyle === 'data'
+        ? undefined
+        : {
+            error: finalError,
+            request,
+            response,
+          };
+    }
+  };
+
+  const makeMethodFn = (method: Uppercase<HttpMethod>) => (options: RequestOptions) =>
+    request({ ...options, method });
+
+  const makeSseFn = (method: Uppercase<HttpMethod>) => async (options: RequestOptions) => {
+    const { opts, url } = await beforeRequest(options);
+    return createSseClient({
+      ...opts,
+      body: opts.body as BodyInit | null | undefined,
+      method,
+      onRequest: async (url, init) => {
+        let request = new Request(url, init);
+        for (const fn of interceptors.request.fns) {
+          if (fn) {
+            request = await fn(request, opts);
+          }
+        }
+        return request;
+      },
+      serializedBody: getValidRequestBody(opts) as BodyInit | null | undefined,
+      url,
+    });
+  };
+
+  const _buildUrl: Client['buildUrl'] = (options) => buildUrl({ ..._config, ...options });
+
+  return {
+    buildUrl: _buildUrl,
+    connect: makeMethodFn('CONNECT'),
+    delete: makeMethodFn('DELETE'),
+    get: makeMethodFn('GET'),
+    getConfig,
+    head: makeMethodFn('HEAD'),
+    interceptors,
+    options: makeMethodFn('OPTIONS'),
+    patch: makeMethodFn('PATCH'),
+    post: makeMethodFn('POST'),
+    put: makeMethodFn('PUT'),
+    request,
+    setConfig,
+    sse: {
+      connect: makeSseFn('CONNECT'),
+      delete: makeSseFn('DELETE'),
+      get: makeSseFn('GET'),
+      head: makeSseFn('HEAD'),
+      options: makeSseFn('OPTIONS'),
+      patch: makeSseFn('PATCH'),
+      post: makeSseFn('POST'),
+      put: makeSseFn('PUT'),
+      trace: makeSseFn('TRACE'),
+    },
+    trace: makeMethodFn('TRACE'),
+  } as Client;
+};

package/src/gen/client/index.ts

@@ -0,0 +1,27 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export type { Auth } from '../core/auth.gen.js';
+export type { QuerySerializerOptions } from '../core/bodySerializer.gen.js';
+export {
+  formDataBodySerializer,
+  jsonBodySerializer,
+  urlSearchParamsBodySerializer,
+} from '../core/bodySerializer.gen.js';
+export { buildClientParams } from '../core/params.gen.js';
+export { serializeQueryKeyValue } from '../core/queryKeySerializer.gen.js';
+export type { ServerSentEventsResult } from '../core/serverSentEvents.gen.js';
+export type { ClientMeta } from '../core/types.gen.js';
+export { createClient } from './client.gen.js';
+export type {
+  Client,
+  ClientOptions,
+  Config,
+  CreateClientConfig,
+  Options,
+  RequestOptions,
+  RequestResult,
+  ResolvedRequestOptions,
+  ResponseStyle,
+  TDataShape,
+} from './types.gen.js';
+export { createConfig, mergeHeaders } from './utils.gen.js';