masterfabric-api-ts

TypeScript client for MasterFabric GraphQL APIs backed by mf-go. It bundles typed operations (auth, user profile, settings, apps, admin helpers, and more) behind a small surface: you provide a transport (how HTTP requests run), and optional logging.

Documentation (operators & integrators): core.masterfabric.co/docs
API / GraphQL reference: core.masterfabric.co/docs/api

Install

npm install masterfabric-api-ts graphql

graphql is a peer dependency (required at runtime for a correct stack alongside graphql-request, which this package uses internally).

Quick start

Wire the default transport (uses graphql-request with per-request headers), then create the API:

import {
  createMfGoGraphqlRequestTransport,
  createMfGoApi,
} from 'masterfabric-api-ts';

const graphqlUrl = 'https://your-mf-go-host/graphql';

const transport = createMfGoGraphqlRequestTransport({
  url: graphqlUrl,
  headers: {
    // Optional: client app identity (mf-go may require this for register / app-scoped calls)
    'X-API-Key': process.env.MF_API_KEY ?? '',
  },
  getHeaders: () => {
    const token = getAccessTokenFromYourApp(); // your session layer
    return token ? { Authorization: `Bearer ${token}` } : {};
  },
  onSessionInvalid: () => {
    // Clear local session, redirect to login, etc.
    clearSessionAndRedirectToLogin();
  },
});

const logger = {
  error: (message: string, context?: Record<string, unknown>) =>
    console.error(message, context),
};

export const mfGoApi = createMfGoApi(transport, logger);

// Examples
await mfGoApi.mfGoAuth.login(email, password);
const profile = await mfGoApi.mfGoUser.me();
const features = await mfGoApi.mfGoApps.appFeatures();

Lower-level entrypoint (single gql function) is available as createMasterfabricClient if you prefer to build your own wrappers.

Implementing in your project

1. Point at the right GraphQL URL

Use the same base URL your MasterFabric environment documents (see docs). Local development is often http://localhost:8080/graphql; production uses your deployed mf-go endpoint.

2. App identity (X-API-Key)

Many flows (for example register or app-scoped operations) expect mf-go to know which client app is calling. That is usually an API key issued from MasterFabric Core for your app. How you pass it:

• Browser / Next.js: only use NEXT_PUBLIC_* for values you accept exposing to clients. Understand that anything in NEXT_PUBLIC_ is visible in the bundle.
• Server / backend jobs: prefer env vars without the public prefix and attach X-API-Key only on the server.

Align with the connection and API key guidance in the documentation.

3. Auth tokens

Attach the user’s access token as Authorization: Bearer … via getHeaders (or your own transport). Refresh / logout semantics are your responsibility; this library does not persist tokens.

4. Session expiry and GraphQL auth errors

When you pass onSessionInvalid to createMfGoGraphqlRequestTransport, certain responses (for example HTTP 401 and common GraphQL auth extension codes) trigger that callback, then throw SessionHandledError. Handle that in UI to avoid duplicate error toasts:

import { isSessionHandledError, formatGqlError } from 'masterfabric-api-ts';

try {
  await mfGoApi.mfGoUser.me();
} catch (e) {
  if (isSessionHandledError(e)) return;
  showError(formatGqlError(e));
}

5. CORS (browser apps)

If the app runs in the browser and mf-go is on another origin, mf-go must allow your web origin. If you see network / fetch failures with no GraphQL body, verify CORS and URL first—not this package.

6. Framework notes

| Environment | Tip | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | Next.js (App Router) | Prefer a small server module or client module that owns createMfGoApi once; add the package to transpilePackages if needed. | | Node scripts | Same transport pattern; no CORS, but still use HTTPS and secrets via env. | | Expo / React Native | Works with your existing fetch / Metro setup; keep the transport on a single module so tokens stay consistent. |

API surface

The factory createMfGoApi returns namespaces such as:

• mfGoAuth — register, login, OTP, refresh, password flows, etc.
• mfGoUser — me, profile updates, addresses, account deletion impact, …
• mfGoSettings, mfGoOrganizations, mfGoNotifications, mfGoTodos, mfGoDevice, mfGoApps, mfGoIntegrations, mfGoPlatformServices (myClientIp, cloudflareTrace — feature-gated; see Platform services), mfGoAdmin, mfGoOTP, …

The schema evolves with mf-go. Not every GraphQL field is wrapped; see MF_GO_TS_CLIENT_GAPS (exported from this package) for areas that may still need manual graphqlRequest calls or new helpers.

Cautions (read before production)

1. Backend version — Operations assume an mf-go schema compatible with the version this package was written against. After server upgrades, retest auth, me, and critical mutations.
2. Secrets — Do not put private keys or admin tokens in client-side env vars. Use X-API-Key only when it is meant to be a public client app key, not a server secret.
3. PII and logging — The optional logger receives structured error context; avoid piping production logs to third parties without a data policy.
4. AGPL-3.0 — This package is released under AGPL-3.0. If you distribute software that links to it, comply with the license or obtain a separate license from the copyright holder.
5. Error shape — GraphQL errors often appear in ClientError.response.errors. Helpers like formatGqlError and mfGoErrorLogContext normalize that for display and logging.

For contributors

If you maintain or extend this package inside the monorepo (new operations, types, transports), read DEVELOPERS.md for setup and PR flow. For agents and Cursor: canonical SKILL.md, shell cheat sheet QUICK_COMMANDS.md, and the mirror under .cursor/skills/masterfabric-api-ts/. Additional maintainers: package.json → contributors.

Starter template

• Next.js: github.com/gurkanfikretgunak/mf-nextjs-starter — App Router, auth + OTP, createMfGoApi / transport wired in src/lib/mf-client.ts; see docs/masterfabric-api-ts.md.

Repository

Monorepo: github.com/masterfabric-mobile/masterfabric-core-base (package path: packages/masterfabric-api-ts).

License

AGPL-3.0