@biab-dev/sdk

Alpha: This package is in an alpha release. APIs and behavior may change without notice. It is not intended for production use yet—evaluate only in development, staging, or experiments.

Phase 4 scaffold for the Business In A Box developer SDK.

This package is the client-side half of the package architecture defined in:

• Phase4.md
• Phase3.md
• Phase2.md

Purpose

The SDK is intended to talk to package-facing host routes under:

/api/package/v1

The host app stays responsible for:

• WorkOS identity mapping
• organization and site ownership checks
• API key verification
• permission enforcement
• Drizzle persistence
• collection schema validation

The package is responsible for:

• typed contracts
• fetch transport
• developer ergonomics
• stable client abstractions

Current Surface

The scaffold currently provides:

• Zod contracts for collections, rows, assets, actions, and auth introspection
• a typed fetch client
• site-scoped resource helpers
• structured API errors

Example

import { createBiabDevClient } from "@biab-dev/sdk";

const client = createBiabDevClient({
	baseUrl: "https://host.example.com/api/package/v1",
	apiKey: process.env.BIAB_API_KEY!,
});

const site = client.site("00000000-0000-0000-0000-000000000000");

await client.introspect();
await site.collections.list();
await site.collections.get("products");
await site.rows.query("products", {
	filters: [{ fieldName: "title", operator: "contains", value: "chair" }],
	limit: 10,
});

Notes

• This package is scaffolded first; the host package routes still need to be implemented.
• Collection contracts intentionally mirror the current BIAB site_data_* model instead of inventing a second schema system.

Publishing to npm

Scoped packages like @biab-dev/sdk only publish if the @biab-dev scope exists on npm and your user is allowed to publish to it. If you skip this, npm publish fails with 404 Scope not found / PUT .../@biab-dev%2fsdk.

1. Create the npm org (required once)

1. Open npmjs.com → Create an organization.
2. Choose the Organization name biab-dev (must match the scope in package.json).
3. Complete signup (a free org can publish public packages).

After this, your logged-in user (check with npm whoami) is typically an owner and can publish @biab-dev/* without extra steps.

If the name biab-dev is already taken on npm, pick another org name and change the name field in package.json to @that-org/sdk (and update imports across this monorepo that reference @biab-dev/sdk).

2. Login

npm login

3. Build and dry run (from this biab-dev folder)

npm run build
npm pack --dry-run

Confirm only dist/, README.md, LICENSE, and package.json are packed ("files": ["dist"]).

4. Publish

npm publish --access public

prepublishOnly runs npm run build automatically before publish.

5. Later releases

Bump version in package.json (or npm version patch|minor|major), then npm publish again.

Consumers install with:

npm install @biab-dev/sdk

Troubleshooting

| Error | Meaning | | --- | --- | | 404 Scope not found | The @biab-dev organization was never created (or you’re logged into a user that isn’t a member). Create the org (step 1) or use a scope you own. | | 403 Forbidden | You’re not allowed to publish this scope. Ask an org owner to add your npm user with publish rights, or publish under your own scope. | | Web login during publish | Normal if you use 2FA — complete the browser prompt, then retry if needed. |