@bike4mind/sdk 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,130 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Bike4Mind, Inc.
+
+Licensed Work:        Bike4Mind (this repository and the components
+                      distributed under this License).
+                      The Licensed Work is (c) 2026 Bike4Mind, Inc.
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      including building, distributing, and commercializing
+                      your own products that incorporate or are built on the
+                      Licensed Work, provided that you may not provide to
+                      third parties a Bike4Mind Service. A "Bike4Mind Service"
+                      is a commercial offering (including a managed, hosted,
+                      or software-as-a-service offering) that allows third
+                      parties — other than your own employees and individual
+                      contractors — to access a substantial portion of the
+                      functionality of the Licensed Work in a manner that
+                      competes with a commercial offering of Bike4Mind, Inc.
+                      For the avoidance of doubt, you may self-host and operate
+                      the Licensed Work on your own hardware or infrastructure
+                      for your own internal purposes (including use by your
+                      organization's employees and individual contractors).
+                      Such internal use — including running it for your own
+                      sovereignty, independent of any hyperscaler or model
+                      provider — is expressly permitted and is not a Bike4Mind
+                      Service.
+
+                      Nominative name use (an additional grant): notwithstanding
+                      the trademark reservation in the Terms below, you may use
+                      the name "Bike4Mind" solely to state accurately that your
+                      product or service is built on, forked from, or derived
+                      from the Licensed Work. This permission does not extend to
+                      using "Bike4Mind" as the name of your own product or
+                      service, or in any manner that implies sponsorship or
+                      endorsement by Bike4Mind, Inc. Retaining the NOTICE file
+                      provided with the Licensed Work is encouraged; and when you
+                      distribute a version on or after its Change Date, retaining
+                      it is required by the Change License (Apache-2.0, Section
+                      4(d)). That obligation attaches to distribution, not to
+                      hosted use.
+
+Change Date:          Two years from the date a given version of the Licensed
+                      Work is first made publicly available. Each version
+                      carries its own Change Date (see Terms). Bike4Mind, Inc.
+                      may, at its discretion, designate an earlier Change Date
+                      for any version.
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact licensing@bike4mind.com.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the second anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of
+the Licensed Work. If you receive the Licensed Work in original or modified form
+from a third party, the terms and conditions set forth in this License apply to
+your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor as
+expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your
+works, and to refer to it using the trademark "Business Source License", as long
+as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business Source
+License" name and trademark, Licensor covenants to MariaDB, and to all other
+recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version, or
+   a license that is compatible with GPL Version 2.0 or a later version, where
+   "compatible" means that software provided under the Change License can be
+   included in a program with software provided under GPL Version 2.0 or a later
+   version. Licensor may specify additional Change Licenses without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as the
+   Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# @bike4mind/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, typed client for the Bike4Mind HTTP API. Its types are generated from the API's OpenAPI spec, so every operation in the spec is callable with typed path params, query, body and response, with no hand-written code per endpoint.
+
+- Runs anywhere with a global `fetch`: Node 18+, Bun, Deno, browsers.
+- One runtime dependency (`eventsource-parser`, for streaming).
+- Responses are typed, not validated.
+
+The full API reference, including scopes, rate limits and async jobs, is served by every deployment at `/api/v1/docs` (the raw spec is at `/api/v1/openapi.json`).
+
+## Install
+
+```sh
+npm install @bike4mind/sdk
+```
+
+## Create a client
+
+```ts
+import { createClient } from '@bike4mind/sdk';
+
+const b4m = createClient({
+  baseUrl: 'https://app.example.com', // your deployment; there is no default
+  apiKey: process.env.B4M_API_KEY, // sent as `Authorization: Bearer b4m_live_...`
+});
+```
+
+Other options:
+
+- `getAuthToken: () => string | undefined | Promise<...>` runs before every request, and its token wins over `apiKey`. Use it for JWTs you refresh yourself.
+- `fetch` is a custom fetch for timeouts, retries, proxies or tests.
+- `headers` are sent on every request.
+
+## Call any operation
+
+`call(operationId, args)` takes the spec's `operationId`. `params` (path), `query` and `body` are typed per operation, and `params`/`body` are required exactly when the operation requires them.
+
+```ts
+const me = await b4m.call('getMe');
+const models = await b4m.call('listModels', { query: { limit: 20 } });
+const project = await b4m.call('getProject', { params: { id: projectId } });
+await b4m.call('deleteProject', { params: { id: projectId } }); // 204: resolves undefined
+```
+
+`call` returns the parsed JSON body. A non-JSON 2xx body (for example the default binary audio from `synthesizeSpeech`) throws; use `raw`, `completions` or the `tts`/`music`/`soundEffects` helpers. For a binary or streamed body, `raw(operationId, args)` returns the 2xx `Response` itself. `operations` maps each id to its `{ method, path }`.
+
+## Stream a completion
+
+```ts
+for await (const event of b4m.completions({
+  model: 'claude-sonnet-5-5',
+  messages: [{ role: 'user', content: 'Hi' }],
+})) {
+  if (event.type === 'content') process.stdout.write(event.text);
+  if (event.type === 'error') throw new Error(event.message);
+}
+```
+
+The endpoint opens the stream before it validates, authenticates or rate-limits, so an invalid body, a rejected key or a rate limit arrives as a yielded `{ type: 'error' }` event, not a thrown error. Only a response that never becomes a stream (a malformed JSON body, a wrong method, a proxy error) throws `B4mApiError`. Pass `{ signal }` to cancel, or `{ url }` to stream from a different endpoint; a relative `url` is joined under `baseUrl`. An absolute `url` receives the same `Authorization` header, so pass only an origin you trust. A stream that ends without `[DONE]` and without an error event throws.
+
+## Chat and image jobs
+
+Chat turns and image generations and edits are queued. Each helper returns a handle whose `poll()` waits for the job to finish:
+
+```ts
+const turn = await b4m.chat({ message: 'Summarize my last notebook' });
+const quest = await turn.poll({ timeoutMs: 120_000 });
+console.log(quest.reply);
+
+const image = await b4m.generateImage({ prompt: 'a red bicycle', model: 'gpt-image-1' });
+const { images } = await image.poll();
+```
+
+`poll` backs off from `intervalMs` (default 1000 ms) up to `maxIntervalMs` (default 5000 ms). It throws `B4mQuestError` when the job ends with `type: "error"` (`reason: 'error'`), ends `stopped` (`'stopped'`), or outlives `timeoutMs` (`'timeout'`). `error.quest` holds the last state. To resume polling a known quest id, use `pollQuest(id)`.
+
+Other async jobs (agent executions, video generations, file uploads) are plain `call`s: start the job, then poll its `get*` operation.
+
+## Audio
+
+`tts`, `music` and `soundEffects` always request `encoding: 'base64'`, so a result too large for the response comes back as the `delivery: 'url'` variant instead of a redirect. A server that predates `encoding` streams raw bytes; the SDK rebuilds the same inline shape from those bytes and the `X-B4M-Audio-*` headers.
+
+```ts
+const result = await b4m.tts({ text: 'Hello', voice: 'alloy' });
+if (result.kind === 'audio' && result.data.delivery === 'inline') {
+  const bytes = Buffer.from(result.data.audio, 'base64');
+}
+```
+
+`tts` also returns `{ kind: 'saved-too-large', data }` when an older server rejects oversized audio with a 413 but kept a saved copy (`data.fabFileId`). To get binary audio directly, use `raw('synthesizeSpeech', { body: { text, encoding: 'binary' } })`.
+
+## Errors
+
+Any non-2xx response throws `B4mApiError`:
+
+```ts
+import { B4mApiError } from '@bike4mind/sdk';
+
+try {
+  await b4m.call('getMe');
+} catch (error) {
+  if (error instanceof B4mApiError) {
+    error.status; // HTTP status
+    error.errorCode; // e.g. 'insufficient_credits'; branch on this, not on the message
+    error.requestId; // body request_id or the X-Request-ID header
+    error.retryAfterSeconds; // from Retry-After on a 429
+    error.body; // the parsed body
+  }
+}
+```
+
+## Types
+
+Generated types are exported for your own code: `paths`, `components`, `Operations`, and the shortcut `Schemas` (for example `Schemas['ErrorResponse']`). Per-operation helpers are `JsonBody<'createProject'>`, `JsonResponse<'getQuest'>`, `PathParams<...>` and `QueryParams<...>`.
+
+These names come straight from the spec (operationIds, schema names such as `getQuestResponse200`, status codes), so they are part of this package's public API: renaming one in the spec is a breaking change for code that imports it.
+
+## Regenerating the types (contributors)
+
+`src/generated/` is generated from `apps/client/public/openapi.json` and checked in. From the repo root:
+
+```sh
+pnpm turbo:openapi:generate   # regenerates the spec, then the SDK types
+```
+
+`pnpm --filter @bike4mind/sdk generate` regenerates only the SDK types from the current spec. CI fails when either is stale.