Getting started

Install

Inside the Forumulate monorepo, @forumulate/sdk is a published npm package — install it with npm install @forumulate/sdk. For an external app, install the published package:

npm install @forumulate/sdk
# or: pnpm add @forumulate/sdk / yarn add @forumulate/sdk

The package ships types and has no runtime dependencies.

Instantiate the client

The constructor takes a single options object:

import { ForumulateClient } from '@forumulate/sdk';

const forumulate = new ForumulateClient({
  baseUrl: 'https://forumulate.com/api', // API origin; a trailing slash is trimmed
  token: process.env.FORUMULATE_TOKEN,   // a Personal Access Token (see Authentication)
});

The full options type:

interface ForumulateClientOptions {
  /** API origin, e.g. https://forumulate.com/api */
  baseUrl: string;
  /** Personal Access Token, sent as `Authorization: Bearer <token>`. */
  token?: string;
  /** Send the session cookie instead (same-origin browser use). Default false. */
  credentials?: boolean;
  /** Inject a fetch implementation (tests / runtimes without global fetch). */
  fetch?: typeof fetch;
}

Notes:

• token and credentials are both optional. Provide token for server-to-server calls. Set credentials: true for a browser app that authenticates with the first-party session cookie (see Authentication). If you provide neither, only the public (unauthenticated) endpoints under client.public.* will work.

• If the runtime has no global fetch, the constructor throws unless you pass fetch.

Your first authenticated call

A complete, runnable Node script that lists the organizations the token can see and creates a public docs space in the first one:

import { ForumulateClient, ForumulateError } from '@forumulate/sdk';

const forumulate = new ForumulateClient({
  baseUrl: 'https://forumulate.com/api',
  token: process.env.FORUMULATE_TOKEN!,
});

async function main() {
  // Who can this token act as?
  const { user } = await forumulate.auth.me();
  console.log('authenticated as', user.email);

  // List orgs, then create a space in the first one.
  const { organizations } = await forumulate.orgs.list();
  const org = organizations[0];
  if (!org) throw new Error('token has no organizations');

  const { space } = await forumulate.spaces.create(org.id, {
    name: 'Docs',
    slug: 'docs',
    type: 'DOCS',       // 'DOCS' | 'BLOG' | 'FORUM'
    visibility: 'PUBLIC' // 'PUBLIC' | 'PRIVATE'
  });
  console.log('created space', space.id);
}

main().catch((err) => {
  if (err instanceof ForumulateError) {
    console.error(`API error ${err.status} [${err.code}]: ${err.message}`);
  } else {
    throw err;
  }
});

Run it with the token in the environment:

FORUMULATE_TOKEN=cft_xxxxxxxx node script.mjs

Browser (same-origin) setup

When the SDK runs in a browser talking to the same origin that serves the app, use the session cookie instead of a token:

const forumulate = new ForumulateClient({ baseUrl: '/api', credentials: true });

This sends credentials: 'include' so the first-party session cookie rides along. Do not embed a PAT in browser code.