What a module receives

A module root is handed a ModuleClient through props and never builds one, so nothing in module code knows about tokens, proxy prefixes or which host it is running inside.

What a module may call

The last two are optional because the host decides whether to attach them. proxyFetch being present does not promise that a given route exists either — the answer to that is the 404 the route itself gives. A module offers the half of itself that answers and does without the other half; it never asks which modules the deployment installed.

execute (the envelope without the throw), iterate (the async-iterable form of subscribe) and dispose are on the full ChatfuelClient and deliberately not on ModuleClient. The only document type a module ever names is TypedDoc, so the generated shape can change — it has already gone from an AST to a printed string — without a module noticing.

Building one

createChatfuelClient is the factory, and the host app is the only place that calls it.

This is the whole of the shell's factory — the file every scaffolded app carries, and the one place that knows where the proxy is mounted:

export function createAppClient(options: AppClientOptions = {}): ModuleClient {
  const getAuthHeader = async (): Promise<string | undefined> => {
    const value = await options.getAccessToken?.();
    return value ? `Bearer ${value}` : undefined;
  };
  const client = createChatfuelClient({
    url: '/chatfuel/graphql',
    wsUrl: '/chatfuel/graphql',
    token: options.getAccessToken,
    onSessionError: options.onSessionError,
  });
  return {
    query: client.query,
    mutate: client.mutate,
    subscribe: client.subscribe,
    onReconnect: client.onReconnect,
    uploadFile: (botId, file, fileType, pluginId) => uploadFile({ botId, file, fileType, pluginId, getAuthHeader }),
    proxyFetch: async (path, init) => {
      const auth = await getAuthHeader();
      const headers = new Headers(init?.headers);
      if (auth) headers.set('authorization', auth);
      return fetch(`${PROXY_PREFIX}${path.startsWith('/') ? path : `/${path}`}`, { ...init, headers });
    },
  };
}

The token in the browser

token takes a string or a getter, and the getter is resolved per request and per socket connect, so a rotating credential works without rebuilding the client. A getter that answers undefined sends no Authorization header at all.

When the session lapses

onSessionError fires when the gate answers AuthSessionRequired (the session is missing or expired) or AuthTenantForbidden (the caller is not a member of this deployment's tenant). It fires once per lapse — the next successful call re-arms it — and it fires from the HTTP and the WebSocket path alike, so the shell can refresh the session or send the user to sign-in without every module handling it. Neither code means the Chatfuel token needs rotating; that one is Unauthorized, and the whole family is on the errors page.

Timeouts and retries

The default HTTP timeout is 30 000 ms. opts.timeoutMs overrides it for one request, which a handful of Chatfuel mutations need: instagramAccountPublishReel sits on Instagram's transcoder for up to five minutes, and raising the client-wide default so four operations can finish would mean a dead upstream is felt five minutes late everywhere. The timeout signal and your own opts.signal are AbortSignal.any-ed together, so an abort stays an abort.

Retries only exist when you pass throttle, and only for network failures, 429 and 5xx. A GraphQL error is never retried. A 429 is always surfaced as an HTTP error rather than an envelope, which is what lets the throttle see it.

Helpers in the same barrel

Everything ~api exports is in packages/api-client/src/index.ts; these are the ones worth knowing before you write the same code yourself.