TypeScript

Better IAM is written in TypeScript and ships declarations with every package. You do not maintain a separate API schema or generate code: the types of every API method, input, and result come from your own betterIam() instance, and the browser client infers them from that instance with a type-only import. When you rename a method or pass a wrong input, the compiler tells you before a request is ever sent.

TypeScript is optional. Every package works from plain JavaScript; the types only add checking and autocompletion.

Setup

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "target": "ES2023",
    "strict": true,
    "skipLibCheck": true
  }
}

import { defineConfig } from 'better-iam/server';
import { sqliteAdapter } from 'better-iam/adapter-sqlite';

export default defineConfig(({ env = process.env } = {}) => ({
  database: sqliteAdapter({ filename: env.BETTER_IAM_DATABASE ?? './iam.db' }),
  secret: env.BETTER_IAM_SECRET ?? '',
  baseURL: env.BETTER_IAM_BASE_URL ?? 'http://localhost:3000',
}));

import { betterIam, configOptions } from 'better-iam/server';
import config from './better-iam.config.js';

// configOptions calls a factory with this process's environment; plain options pass through.
export const iam = betterIam(await configOptions(config));

Inference from the instance

betterIam() has no hand-written return type: its type is whatever the instance contains, exported as BetterIam (ReturnType<typeof betterIam>). Every method under iam.api is a plain async function, so the usual TypeScript utilities give you its input and result types without any Better IAM helper:

import type { iam } from './iam.js';

// The input of roles.create (its second parameter, after the credential).
export type RoleInput = Parameters<typeof iam.api.roles.create>[1];
// What roles.create resolves to.
export type CreatedRole = Awaited<ReturnType<typeof iam.api.roles.create>>;
// The caller as auth.getSession returns it.
export type CurrentSession = Awaited<ReturnType<typeof iam.api.auth.getSession>>;

Results that can take more than one form are unions, so narrow them before use:

import { iam } from './iam.js';

const result = await iam.api.auth.signIn({ tenantId, email, password });
if ('mfaRequired' in result) {
  // result is the MFA challenge: { mfaRequired: true, challenge, enrollmentRequired, ... }
} else {
  // result has the session token and session
}

Api from better-iam/server is the type of iam.api itself, for code that receives the API object rather than the whole instance.

The typed client

createIamClient<typeof iam>() infers the client from the server instance. Import the instance with import type, so no server code (database drivers, password hashing) reaches the browser bundle.

import { createIamClient } from 'better-iam/client';
import type { iam } from './iam.js';

export const client = createIamClient<typeof iam>();

const role = await client.roles.create({ tenantId, name: 'Editor', permissions: ['documents:read'] });
//    ^? the same result type as iam.api.roles.create

The client's type, IamClient<typeof iam>, maps each server method to a client method:

options is ClientCallOptions: { signal?: AbortSignal; headers?: HeadersInit }. Plugin endpoints are not part of the instance's type, so client.$request<Result>(path, input) takes the result type as a type argument.

To pass the client through props or context, type it with IamClient:

import type { IamClient } from 'better-iam/client';
import type { iam } from '../lib/iam.js';

export function Members({ client, tenantId }: { client: IamClient<typeof iam>; tenantId: string }) {
  // client.identities.list({ tenantId }) is fully typed here.
  return null;
}

The UI bindings take the client's type as a type argument. In React, useIamClient<typeof client>() returns the typed client and useSession<typeof client>() types the session as getSession returns it. SessionOf<typeof client> from better-iam/client/session names that session type directly.

import { useSession } from '@better-iam/react';
import type { client } from '../lib/iam-client.js';

export function Profile() {
  const { status, session } = useSession<typeof client>();
  return status === 'authenticated' ? <p>{session?.identity.name}</p> : null;
}

Typed builders

import { definePolicy } from 'better-iam';

export const readDocuments = definePolicy({
  version: 1,
  statements: [{ effect: 'allow', actions: ['documents:read'], resources: ['document/*'] }],
});

Exported types

The umbrella package re-exports each package's types under the matching subpath. These are the ones you reach for most; Types documents their fields and Exports lists everything.

Individual packages export the same names: @better-iam/server, @better-iam/client, @better-iam/client/session, and @better-iam/cli.

What is checked only at runtime

Some values are plain strings in the types because their valid set lives in your configuration or database, not in the code:

The instance also validates its own options at construction and throws INVALID_CONFIG, so options that type-check but break a rule (a basePath with a trailing slash, an http: baseURL outside localhost) still fail at startup.

Next steps