SDK Builder base code

Build SDK Clients for Faable APIs

Install

 npm install @faable/sdk-base

Building an API client

Extend FaableApi and call the static create factory:

import { FaableApi } from "@faable/sdk-base";
import type { ApiParams } from "@faable/sdk-base";

export class MyApi extends FaableApi {
  constructor(params?: ApiParams) {
    super({ baseURL: "https://api.example.com", ...params });
  }
  getThing(id: string) {
    return this.fetcher.get(`/thing/${id}`);
  }
}

Authentication (pluggable, Octokit-style)

Auth is explicit — strategies never read environment variables. You pick an authStrategy and pass its config in auth; the chosen strategy drives the type of auth, so the editor autocompletes the right fields and rejects the wrong ones.

import { authClientCredentials, authApikey } from "@faable/sdk-base";

// client_credentials — the DEFAULT strategy. `auth` requires
// { client_id, client_secret }.
const api = MyApi.create({
  baseURL: "https://my-account.auth.faable.link",
  authStrategy: authClientCredentials,
  auth: { client_id: "...", client_secret: "..." },
});

// api key — `auth` requires { apikey }.
const api2 = MyApi.create({
  baseURL: "https://api.example.com",
  authStrategy: authApikey,
  auth: { apikey: "fak_xxx" },
});

authClientCredentials requests its token from <baseURL>/oauth/token by default. When the API host is not the auth server, point the token request at the right host with auth.domain:

auth: { client_id: "...", client_secret: "...", domain: "https://auth.example.com" }

Writing a custom strategy

A strategy is a builder (config, context) => { headers() }:

import type { AuthStrategyBuilder } from "@faable/sdk-base";

type BearerConfig = { token: string };

export const authBearer: AuthStrategyBuilder<BearerConfig> = (config) => {
  if (!config?.token) throw new Error("authBearer: `auth.token` is required");
  return {
    headers: async () => ({ authorization: `Bearer ${config.token}` }),
  };
};

context carries the api's domain (its baseURL) and debug flag, so a token-minting strategy can reach the auth server without extra config.