NestJS

Use @stitchapi/nest when you want your stitches available through NestJS dependency injection — configured once, injected into services as typed dependencies, with the framework's Logger and ConfigService wired in and shutdown handled for you. It is a thin peer-dependency package that adds no capability of its own: it wires StitchAPI's shared-runtime primitive (one store, one trace sink, a trusted principal boundary) into Nest's DI graph, so core stays untouched.

Example

Install the package alongside core:

npm install @stitchapi/nest@rc stitchapi@rc

Configure the shared client once in your root module. forRootAsync resolves its options from an injected factory, which is how ConfigService reaches the base URL, secrets, and store. The event stream is bridged to the Nest Logger by default — nothing to switch on:

// app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { StitchModule, fromNestConfig } from '@stitchapi/nest';
import { bearer } from 'stitchapi/auth';

@Module({
    imports: [
        StitchModule.forRootAsync({
            imports: [ConfigModule],
            inject: [ConfigService],
            useFactory: (config: ConfigService) => ({
                baseUrl: config.getOrThrow('API_BASE_URL'),
                auth: bearer(fromNestConfig(config)('API_TOKEN')),
            }),
        }),
    ],
})
export class AppModule {}

Declare a stitch with defineStitch, register it per feature with forFeature, and inject it as a typed dependency:

// users.module.ts
import { Injectable, Module } from '@nestjs/common';
import {
    InjectStitch,
    type Injected,
    StitchModule,
    defineStitch,
} from '@stitchapi/nest';
import { z } from 'zod';

export const GetUser = defineStitch('GET_USER', (api) =>
    api.stitch({
        path: '/users/{id}',
        output: z.object({ id: z.number(), name: z.string() }),
    }),
);

@Module({ imports: [StitchModule.forFeature({ stitches: [GetUser] })] })
export class UsersModule {}

@Injectable()
export class UsersService {
    constructor(
        @InjectStitch(GetUser)
        private readonly getUser: Injected<typeof GetUser>,
    ) {}

    find(id: string) {
        return this.getUser({ params: { id } });
    }
}

Injected<typeof GetUser> keeps the injection-site type tied to the definition, so the injected getUser is the same typed callable a stitch always is — awaited for the validated result, or .stream()-ed for the event stream.

Options

forRoot({ store, trace, ...defaults }) configures the app-wide infrastructure — one store, one trace sink — plus the shared config (baseUrl, auth, retry, throttle, …) every stitch inherits; forRootAsync resolves the same options from an injected factory. forFeature({ stitches, seam }) registers injectable stitches and, optionally, a per-upstream seam built over the shared store and trace — seam: { config, token? } (its config is the feature seam's baseUrl/auth/…); omit seam to attach the stitches to the default one.

Two bridges connect the framework, and neither changes core:

• logger bridges a stitch's event stream into the Nest Logger as the seam's TraceSink — on by default, matching the Fastify plugin. It logs only metadata (name, method, scrubbed URL, status, attempts, timing) — never bodies or headers. Disable it with logger: false, or drop the happy path with logger: { lifecycle: false }; an explicit trace wins over the bridge.
• fromNestConfig(config)('KEY') is a ConfigService-backed secret resolver — the ConfigService twin of env(). It resolves synchronously at call time, so the credential never lands on the config or in a trace.

For multi-tenancy, bind a principal per request with seam.as(...). The principal scopes sessions and cache over the one shared store, so each tenant gets its own login while the connection pool stays shared:

import { Scope } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import { STITCH_SEAM } from '@stitchapi/nest';
import type { Seam } from 'stitchapi';

const TenantSeam = {
    provide: 'TENANT_SEAM',
    scope: Scope.REQUEST,
    useFactory: (root: Seam, req: { user?: { tenantId?: string } }) =>
        root.as(req.user?.tenantId ?? 'anonymous'),
    inject: [STITCH_SEAM, REQUEST],
};

See also