fix: accept a Supermemory API key programmatically in the OpenAI integration

[rajarshidattapy]

Summary

Fixes #1242.

The OpenAI integration was the only one that couldn't accept an API key programmatically.

The Vercel, Mastra, and Voltagent integrations all resolve:

options.apiKey ?? process.env.SUPERMEMORY_API_KEY

through the shared validateApiKey helper (src/shared/context.ts).

The OpenAI middleware instead read process.env.SUPERMEMORY_API_KEY directly in two places and exposed no apiKey field on OpenAIMiddlewareOptions.

As a result, withSupermemory() hard-threw whenever the key wasn't available as a process environment variable (for example when using a secrets manager, an edge runtime, or a multi-tenant server with a per-request key), with no way to supply one programmatically.

Fix

This PR adds an optional apiKey field and routes all API key resolution through the shared validateApiKey() helper, bringing the OpenAI integration in line with the others.

src/openai/middleware.ts

• Adds apiKey?: string to OpenAIMiddlewareOptions
• Resolves the key once via:

validateApiKey(options?.apiKey)

• Threads the resolved key through:
  • supermemoryProfileSearch() (now accepts an apiKey parameter instead of reading process.env when constructing the Authorization header)
  • addSystemPrompt()
• Passes the resolved key into addMemoryTool() instead of process.env.SUPERMEMORY_API_KEY

src/openai/index.ts

• Replaces:

if (!process.env.SUPERMEMORY_API_KEY) {
  throw ...
}

with:

validateApiKey(options.apiKey)

This preserves the existing fail-fast behavior while allowing callers to provide the API key programmatically.

Documentation

Updated the OpenAI JSDoc @throws descriptions to match the shared behavior:

neither options.apiKey nor process.env.SUPERMEMORY_API_KEY is provided.

Example

The following now works:

const client = withSupermemory(openai, {
  containerTag: "user-123",
  customId: "conversation-456",
  apiKey: await secrets.get("supermemory"),
})

Previously this threw:

Error: SUPERMEMORY_API_KEY is not set

Testing

Added:

• src/openai/middleware.test.ts (4 tests)

The tests mock the SDK and stub fetch, so no network access is required.

I also verified that the new tests reproduce the original bug.

Against main, the two new capability tests fail with:

× accepts an API key from options when the env var is not set
  → expected [Function] to not throw an error but
    'Error: SUPERMEMORY_API_KEY is not set' was thrown

The two backward-compatibility tests continue to pass before and after the change:

• environment variable fallback
• throwing when neither options.apiKey nor SUPERMEMORY_API_KEY is provided

One test additionally verifies that the outgoing /v4/profile request contains:

Authorization: Bearer <key>

confirming the supplied key is propagated all the way to the HTTP request rather than only accepted by the API surface.

Checks

Per CONTRIBUTING.md:

• ✅ vitest — 80 passing, 0 failing assertions
• ✅ check-types — 146 errors on this branch, 146 on main (no new errors; existing ones are in test/ files and src/openai/tools.ts)
• ✅ build
• ✅ format-lint (Biome clean)

Breaking changes

None.

apiKey is optional, and SUPERMEMORY_API_KEY remains the fallback, so existing code continues to work unchanged.

The only behavioral change is that a programmatically supplied API key is now honored instead of causing an exception.

[ishaanxgupta]

@rajarshidattapy please fix the conflicts

[rajarshidattapy]

@ishaanxgupta give me 5 mins, on it.

[rajarshidattapy]

@ishaanxgupta done, you can merge it now.

[ishaanxgupta]

I still see some conflicts

[rajarshidattapy]

@ishaanxgupta Thanks for catching that. I pulled the latest upstream/main again, resolved the remaining conflicts, and pushed the changes. It should be ready for another look.

[MaheshtheDev]

Included in #1594 with your commit and authorship intact, plus a Co-Authored-By trailer in the description so the credit survives the squash merge.

Two things on top: we resolved the conflicts with current main (deduplicateMemories was renamed to deduplicateMemoriesForMode, and main already documents the addMemory default as "always"), and we dropped middleware.test.ts.

Thanks @rajarshidattapy.