@mixedbread/sdk 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 0.5.0 (2025-05-07)
+
+Full Changelog: [v0.4.0...v0.5.0](https://github.com/mixedbread-ai/mixedbread-ts/compare/v0.4.0...v0.5.0)
+
+### Features
+
+* **api:** update via SDK Studio ([9421b8d](https://github.com/mixedbread-ai/mixedbread-ts/commit/9421b8dac8c4eab0a745e11058d7387f70177aeb))
+* **api:** update via SDK Studio ([19d1598](https://github.com/mixedbread-ai/mixedbread-ts/commit/19d15980550109a207ef74da87c14ed64e2612a5))
+* **client:** add withOptions helper ([cc39c84](https://github.com/mixedbread-ai/mixedbread-ts/commit/cc39c842d23f2ab3c473b82e7e2914eb2a1fed14))
+* more gracefully handle $refs and work around schema limitations ([294db31](https://github.com/mixedbread-ai/mixedbread-ts/commit/294db3165718ce7752b0e4f779cd648d47c17b4c))
+
+
+### Bug Fixes
+
+* **internal:** fix file uploads in node 18 jest ([2bb600d](https://github.com/mixedbread-ai/mixedbread-ts/commit/2bb600dd7d69d21527879ec4fd29cb244e7716cf))
+* **mcp:** remove ajv dependency so MCP servers are more compatible with Cloudflare Workers ([9a0f0a6](https://github.com/mixedbread-ai/mixedbread-ts/commit/9a0f0a640cf4c34216fffce2e2967cd98594f9bd))
+
+
+### Chores
+
+* **ci:** add timeout thresholds for CI jobs ([a68ffcc](https://github.com/mixedbread-ai/mixedbread-ts/commit/a68ffccb66c7ad79887369c83261af71fdb3869f))
+* **ci:** only use depot for staging repos ([d3a9912](https://github.com/mixedbread-ai/mixedbread-ts/commit/d3a991253e679040b9cb44728e82ec1a33be145e))
+* **client:** drop support for EOL node versions ([c995474](https://github.com/mixedbread-ai/mixedbread-ts/commit/c9954746fd8a970c0fc28aa683e72b3e8694f8be))
+* **client:** minor internal fixes ([1b43dad](https://github.com/mixedbread-ai/mixedbread-ts/commit/1b43dad1fbc09a382f51b57b32588f3347e85b87))
+* **internal:** codegen related update ([755d9f9](https://github.com/mixedbread-ai/mixedbread-ts/commit/755d9f9451196171b169ae36d9e1c757332a5535))
+* **internal:** codegen related update ([c3e0876](https://github.com/mixedbread-ai/mixedbread-ts/commit/c3e087658a0f8b43a87b8656ee20b914b6634be6))
+* **internal:** refactor utils ([6a22a08](https://github.com/mixedbread-ai/mixedbread-ts/commit/6a22a088a0c112dca1f7f2271b4b95cd9110de00))
+* **internal:** share typescript helpers ([24e088a](https://github.com/mixedbread-ai/mixedbread-ts/commit/24e088a19695be197f935611c334c233a5aaeab9))
+* **perf:** faster base64 decoding ([e8c7f9a](https://github.com/mixedbread-ai/mixedbread-ts/commit/e8c7f9ae682c8fc9e0c67e1730f8fc79f08f8b73))
+
+
+### Documentation
+
+* add examples to tsdocs ([929c293](https://github.com/mixedbread-ai/mixedbread-ts/commit/929c293b7a6fee0645408307c2cab96600fbdd4b))
+* **readme:** fix typo ([0b4473f](https://github.com/mixedbread-ai/mixedbread-ts/commit/0b4473f6b8b9eac8b351badb22db5438bddc9e43))
+
+## 0.4.0 (2025-04-10)
+
+Full Changelog: [v0.3.0...v0.4.0](https://github.com/mixedbread-ai/mixedbread-ts/compare/v0.3.0...v0.4.0)
+
+### Features
+
+* **api:** update via SDK Studio ([68874d1](https://github.com/mixedbread-ai/mixedbread-ts/commit/68874d18ab8856b36afcee59465d5ade72cfdbcf))
+* **api:** update via SDK Studio ([227709d](https://github.com/mixedbread-ai/mixedbread-ts/commit/227709df8b0b9294f29160f2bd86d0aaacdf5017))
+
+
+### Chores
+
+* configure new SDK language ([33ad60b](https://github.com/mixedbread-ai/mixedbread-ts/commit/33ad60b9de23d8de6f1dfa31d90f6b1094b9bcd8))
+* **tests:** improve enum examples ([#173](https://github.com/mixedbread-ai/mixedbread-ts/issues/173)) ([4e10ecc](https://github.com/mixedbread-ai/mixedbread-ts/commit/4e10ecc0ff7942e4bce1059802c56a678746524e))
+
 ## 0.3.0 (2025-04-08)
 
 Full Changelog: [v0.2.2...v0.3.0](https://github.com/mixedbread-ai/mixedbread-ts/compare/v0.2.2...v0.3.0)

package/README.md

@@ -1,4 +1,4 @@
-# Mixedbread API Node/TypeScript SDK API Library
+# Mixedbread API TypeScript SDK API Library
 
 [![NPM version](https://img.shields.io/npm/v/@mixedbread/sdk.svg)](https://npmjs.org/package/@mixedbread/sdk) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@mixedbread/sdk)
 
@@ -69,7 +69,6 @@ Request parameters that correspond to file uploads can be passed in many differe
 
 ```ts
 import fs from 'fs';
-import fetch from 'node-fetch';
 import Mixedbread, { toFile } from '@mixedbread/sdk';
 
 const client = new Mixedbread();
@@ -111,7 +110,7 @@ async function main() {
 main();
 ```
 
-Error codes are as followed:
+Error codes are as follows:
 
 | Status Code | Error Type                 |
 | ----------- | -------------------------- |
@@ -202,8 +201,10 @@ while (page.hasNextPage()) {
 ### Accessing raw Response data (e.g., headers)
 
 The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
+This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
 
 You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
+Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
 
 <!-- prettier-ignore -->
 ```ts
@@ -218,6 +219,59 @@ console.log(raw.headers.get('X-My-Header'));
 console.log(vectorStore.id);
 ```
 
+### Logging
+
+> [!IMPORTANT]
+> All log messages are intended for debugging only. The format and content of log messages
+> may change between releases.
+
+#### Log levels
+
+The log level can be configured in two ways:
+
+1. Via the `MIXEDBREAD_LOG` environment variable
+2. Using the `logLevel` client option (overrides the environment variable if set)
+
+```ts
+import Mixedbread from '@mixedbread/sdk';
+
+const client = new Mixedbread({
+  logLevel: 'debug', // Show all log messages
+});
+```
+
+Available log levels, from most to least verbose:
+
+- `'debug'` - Show debug messages, info, warnings, and errors
+- `'info'` - Show info messages, warnings, and errors
+- `'warn'` - Show warnings and errors (default)
+- `'error'` - Show only errors
+- `'off'` - Disable all logging
+
+At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
+Some authentication-related headers are redacted, but sensitive data in request and response bodies
+may still be visible.
+
+#### Custom logger
+
+By default, this library logs to `globalThis.console`. You can also provide a custom logger.
+Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
+
+When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
+below the configured level will not be sent to your logger.
+
+```ts
+import Mixedbread from '@mixedbread/sdk';
+import pino from 'pino';
+
+const logger = pino();
+
+const client = new Mixedbread({
+  logger: logger.child({ name: 'Mixedbread' }),
+  logLevel: 'debug', // Send all messages to pino, allowing it to filter
+});
+```
+
 ### Making custom/undocumented requests
 
 This library is typed for convenient access to the documented API. If you need to access undocumented
@@ -264,66 +318,85 @@ validate or strip extra properties from the response from the API.
 
 ### Customizing the fetch client
 
-By default, this library uses `node-fetch` in Node, and expects a global `fetch` function in other environments.
+By default, this library expects a global `fetch` function is defined.
 
-If you would prefer to use a global, web-standards-compliant `fetch` function even in a Node environment,
-(for example, if you are running Node with `--experimental-fetch` or using NextJS which polyfills with `undici`),
-add the following import before your first import `from "Mixedbread"`:
+If you want to use a different `fetch` function, you can either polyfill the global:
 
 ```ts
-// Tell TypeScript and the package to use the global web fetch instead of node-fetch.
-// Note, despite the name, this does not add any polyfills, but expects them to be provided if needed.
-import '@mixedbread/sdk/shims/web';
-import Mixedbread from '@mixedbread/sdk';
+import fetch from 'my-fetch';
+
+globalThis.fetch = fetch;
 ```
 
-To do the inverse, add `import "@mixedbread/sdk/shims/node"` (which does import polyfills).
-This can also be useful if you are getting the wrong TypeScript types for `Response` ([more details](https://github.com/mixedbread-ai/mixedbread-ts/tree/main/src/_shims#readme)).
+Or pass it to the client:
 
-### Logging and middleware
+```ts
+import Mixedbread from '@mixedbread/sdk';
+import fetch from 'my-fetch';
 
-You may also provide a custom `fetch` function when instantiating the client,
-which can be used to inspect or alter the `Request` or `Response` before/after each request:
+const client = new Mixedbread({ fetch });
+```
+
+### Fetch options
+
+If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
 
 ```ts
-import { fetch } from 'undici'; // as one example
 import Mixedbread from '@mixedbread/sdk';
 
 const client = new Mixedbread({
-  fetch: async (url: RequestInfo, init?: RequestInit): Promise<Response> => {
-    console.log('About to make a request', url, init);
-    const response = await fetch(url, init);
-    console.log('Got response', response);
-    return response;
+  fetchOptions: {
+    // `RequestInit` options
   },
 });
 ```
 
-Note that if given a `DEBUG=true` environment variable, this library will log all requests and responses automatically.
-This is intended for debugging purposes only and may change in the future without notice.
+#### Configuring proxies
+
+To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
+options to requests:
 
-### Configuring an HTTP(S) Agent (e.g., for proxies)
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
 
-By default, this library uses a stable agent for all http/https requests to reuse TCP connections, eliminating many TCP & TLS handshakes and shaving around 100ms off most requests.
+```ts
+import Mixedbread from '@mixedbread/sdk';
+import * as undici from 'undici';
 
-If you would like to disable or customize this behavior, for example to use the API behind a proxy, you can pass an `httpAgent` which is used for all requests (be they http or https), for example:
+const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
+const client = new Mixedbread({
+  fetchOptions: {
+    dispatcher: proxyAgent,
+  },
+});
+```
+
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
 
-<!-- prettier-ignore -->
 ```ts
-import http from 'http';
-import { HttpsProxyAgent } from 'https-proxy-agent';
+import Mixedbread from '@mixedbread/sdk';
 
-// Configure the default for all requests:
 const client = new Mixedbread({
-  httpAgent: new HttpsProxyAgent(process.env.PROXY_URL),
+  fetchOptions: {
+    proxy: 'http://localhost:8888',
+  },
 });
+```
 
-// Override per-request:
-await client.vectorStores.create({
-  httpAgent: new http.Agent({ keepAlive: false }),
+<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+
+```ts
+import Mixedbread from 'npm:@mixedbread/sdk';
+
+const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
+const client = new Mixedbread({
+  fetchOptions: {
+    client: httpClient,
+  },
 });
 ```
 
+## Frequently Asked Questions
+
 ## Semantic versioning
 
 This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
@@ -338,12 +411,12 @@ We are keen for your feedback; please open an [issue](https://www.github.com/mix
 
 ## Requirements
 
-TypeScript >= 4.5 is supported.
+TypeScript >= 4.9 is supported.
 
 The following runtimes are supported:
 
 - Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
-- Node.js 18 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
+- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
 - Deno v1.28.0 or higher.
 - Bun 1.0 or later.
 - Cloudflare Workers.

package/api-promise.d.mts

@@ -0,0 +1,2 @@
+export * from "./core/api-promise.mjs";
+//# sourceMappingURL=api-promise.d.mts.map

package/api-promise.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.d.mts","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":""}

package/api-promise.d.ts

@@ -0,0 +1,2 @@
+export * from "./core/api-promise.js";
+//# sourceMappingURL=api-promise.d.ts.map

package/api-promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.d.ts","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":""}

package/api-promise.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("./internal/tslib.js");
+/** @deprecated Import from ./core/api-promise instead */
+tslib_1.__exportStar(require("./core/api-promise.js"), exports);
+//# sourceMappingURL=api-promise.js.map

package/api-promise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.js","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":";;;AAAA,yDAAyD;AACzD,gEAAmC"}

package/api-promise.mjs

@@ -0,0 +1,2 @@
+export * from "./core/api-promise.mjs";
+//# sourceMappingURL=api-promise.mjs.map

package/api-promise.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-promise.mjs","sourceRoot":"","sources":["src/api-promise.ts"],"names":[],"mappings":""}

package/bin/cli

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('child_process');
+
+const commands = {
+  migrate: {
+    description: 'Run migrations to update to the latest major SDK version',
+    fn: () => {
+      const result = spawnSync(
+        'npx',
+        [
+          '-y',
+          'https://github.com/stainless-api/migrate-ts/releases/download/0.0.2/stainless-api-migrate-0.0.2-6.tgz',
+          '--migrationConfig',
+          require.resolve('./migration-config.json'),
+          ...process.argv.slice(3),
+        ],
+        { stdio: 'inherit' },
+      );
+      if (result.status !== 0) {
+        process.exit(result.status);
+      }
+    },
+  },
+};
+
+function exitWithHelp() {
+  console.log(`Usage: mixedbread-sdk <subcommand>`);
+  console.log();
+  console.log('Subcommands:');
+
+  for (const [name, info] of Object.entries(commands)) {
+    console.log(`  ${name}  ${info.description}`);
+  }
+
+  console.log();
+  process.exit(1);
+}
+
+if (process.argv.length < 3) {
+  exitWithHelp();
+}
+
+const commandName = process.argv[2];
+
+const command = commands[commandName];
+if (!command) {
+  console.log(`Unknown subcommand ${commandName}.`);
+  exitWithHelp();
+}
+
+command.fn();

package/bin/migration-config.json

@@ -0,0 +1,73 @@
+{
+  "pkg": "@mixedbread/sdk",
+  "githubRepo": "https://github.com/mixedbread-ai/mixedbread-ts",
+  "clientClass": "Mixedbread",
+  "methods": [
+    {
+      "base": "vectorStores.files",
+      "name": "retrieve",
+      "params": [
+        {
+          "type": "param",
+          "key": "file_id",
+          "location": "path"
+        },
+        {
+          "type": "params",
+          "maybeOverload": false
+        },
+        {
+          "type": "options"
+        }
+      ],
+      "oldParams": [
+        {
+          "type": "param",
+          "key": "vector_store_id",
+          "location": "path"
+        },
+        {
+          "type": "param",
+          "key": "file_id",
+          "location": "path"
+        },
+        {
+          "type": "options"
+        }
+      ]
+    },
+    {
+      "base": "vectorStores.files",
+      "name": "delete",
+      "params": [
+        {
+          "type": "param",
+          "key": "file_id",
+          "location": "path"
+        },
+        {
+          "type": "params",
+          "maybeOverload": false
+        },
+        {
+          "type": "options"
+        }
+      ],
+      "oldParams": [
+        {
+          "type": "param",
+          "key": "vector_store_id",
+          "location": "path"
+        },
+        {
+          "type": "param",
+          "key": "file_id",
+          "location": "path"
+        },
+        {
+          "type": "options"
+        }
+      ]
+    }
+  ]
+}