@bandruption/typescript-sdk

TypeScript type definitions for the Bandruption API. Published from the bandruption-flagship-platform monorepo.

What this package is

This is a types-only package. It contains the curated public AppRouter type, the SdkRouter type for the stable sdk.* contract, and nothing else — no runtime JavaScript. Consumers use it to construct a fully type-safe tRPC client against approved public Bandruption API procedures.

This follows the official tRPC pattern for cross-repo type sharing and the recipe described in billyjacoby's guide.

Installation

Install as a devDependency alongside the tRPC runtime packages you'll actually use:

npm install -D @bandruption/typescript-sdk
npm install @trpc/client @trpc/react-query @tanstack/react-query react superjson

Installing as a devDependency keeps the types' transitive dependencies out of your runtime bundle.

Usage

import type { AppRouter } from '@bandruption/typescript-sdk';
import { httpBatchLink } from '@trpc/client';
import { createTRPCReact } from '@trpc/react-query';
import superjson from 'superjson';

export const trpc = createTRPCReact<AppRouter>();

export function createTrpcClient(url: string) {
  return trpc.createClient({
    links: [httpBatchLink({ url, transformer: superjson })],
  });
}

SDK v1 consumers can use the narrower mounted contract when they only need the stable sdk.* API:

import type { SdkRouter } from '@bandruption/typescript-sdk';
import { createTRPCReact } from '@trpc/react-query';

export const sdkTrpc = createTRPCReact<SdkRouter>();

// Matches the server's real /trpc path: sdk.health.check
sdkTrpc.sdk.health.check.useQuery();

What's exported

The curated public AppRouter type derived from publicAppRouter, plus the SdkRouter type derived from a public declaration contract that mirrors the server's runtime appRouter.sdk mount. The current public app surface includes health.check, blog.list, blog.getBySlug, and the service-authenticated line.dispatch contract. The SDK v1 namespace taxonomy is sdk.health, sdk.entity, sdk.events, sdk.ticketTypes, sdk.content, sdk.merch, sdk.bounties, sdk.orders, and sdk.uploads; sdk.health.check is the first callable procedure while the domain namespaces are intentionally reserved for approved follow-on SDK tickets.

The package does not expose the internal app router, runtime code, zod schemas, service interfaces, superadmin routes, SKUNKWORKS routes, or provider-specific implementation routes. If you need additional shared types or runtime helpers, define them in your consumer app or open an issue requesting an explicit named export — broad re-exports are intentionally avoided to keep the API surface narrow.

Versioning

Versions are bumped manually via the Publish TypeScript SDK GitHub Actions workflow in the source monorepo. Each published version corresponds to a tag of the form typescript-sdk-vX.Y.Z.

The workflow is dry-run by default. It validates the requested semver, builds the public declaration bundle, checks declaration import sources, runs a scratch consumer TypeScript smoke test, then runs npm publish --dry-run. To publish, run the workflow from main, set publish=true, and set confirm_leak_gates exactly to:

I confirm BAN-1004 leak gates passed

Publisher verification

Run these checks before requesting a publish:

NX_SKIP_REMOTE_CACHE=true npx nx run @bandruption/typescript-sdk:build --skip-nx-cache
npm run check:declaration --workspace @bandruption/typescript-sdk
npm run smoke:consumer --workspace @bandruption/typescript-sdk

The declaration gate allowlist is intentionally narrow: @trpc/client, @trpc/react-query, @trpc/server, @tanstack/react-query, react, superjson, and zod. The current emitted declaration should only report @trpc/server. It must not report @shared/*, raw Prisma, Spotify, PayPal, Metaplex, UMI, Solana, Firebase Admin, Google Cloud SDK imports, internal tRPC context/service types, SKUNKWORKS, or superadmin markers.

Retry and rollback

If the workflow fails before publishing, fix the reported build, declaration, auth, smoke-test, or branch-protection issue and rerun with the same version.

Published versions on npm are immutable. If a bad version is published, do not try to overwrite it. Deprecate the bad version, publish a new patch version, and update affected consumer lockfiles:

npm deprecate @bandruption/[email protected] "Bad declaration package; use X.Y.(Z+1)"

If publish succeeds but the tag push fails, verify the package exists on npm, create the missing typescript-sdk-vX.Y.Z tag on the published source commit, and push only that tag.