@mitralab.io/functions-sdk 0.2.0-beta.1 → 0.2.0-beta.2

package/README.md

@@ -28,6 +28,7 @@ It also accepts the canonical aliases:
 - `MITRA_PLATFORM_ACCESS_TOKEN`
 - `MITRA_APP_ID`
 - `MITRA_DATA_SOURCE_ID`, retained for runtime compatibility when already resolved
+- `MITRA_API_KEY`, read by `createClientFromApiKey()`
 
 When only the existing names are present, the SDK removes a trailing `/legacy` from
 `MITRA_BASE_URL` and calls the owning services from that gateway root. It forwards `MITRA_TOKEN`
@@ -61,6 +62,39 @@ const mitra = createClient({
 
 `createClientFromEnvironment(env)` is available when a function needs to supply a specific environment object, such as in tests.
 
+### Authenticating with an api key
+
+Outside the Functions runtime there is no token to inject. A process that runs on its own — a cron,
+a background collector, another service — authenticates with an api key created in
+**Settings -> API keys**:
+
+```typescript
+import { createClientFromApiKey } from "@mitralab.io/functions-sdk"
+
+const mitra = await createClientFromApiKey({
+  apiUrl: "https://api.example.com",
+  apiKey: process.env.MITRA_API_KEY,
+  appId: "app-id",
+})
+```
+
+The factory is asynchronous because trading the key for a token is a network call. It fails there,
+where the client is built, rather than inside an unrelated call later.
+
+Which key to create depends on what the process does. A **Business** key reaches the published
+product: read and write records, run queries, execute functions and integrations. A **Developer**
+key adds authoring — schema, code, publishing. An **Administrator** key belongs to a workspace
+rather than a product; the SDK issues the token for the configured `appId` from it, and the
+platform decides on that call what this user actually reaches in that product.
+
+The token lasts 48 hours and the exchange returns no refresh token, by design: the key does not
+expire and is revoked by deleting it, so the SDK renews by trading the key again. It does this on
+its own when a request comes back unauthorized, which is why a process may stay up for weeks. Keep
+the key where you keep passwords — it is valid until someone deletes it.
+
+This authentication path expects a server runtime. Never ship an api key in code that reaches a
+browser: it would be served to every visitor.
+
 ## Initialization
 
 Entity and Custom Query operations use the app identity from the token and `X-App-Id`, so they are

package/contracts/sdk-core-v0.2.0-beta.3.manifest.json

@@ -0,0 +1,15 @@
+{
+  "contract": "SDK-PARITY-001",
+  "version": "0.2.0-beta.3",
+  "dependency": {
+    "package": "@mitralab.io/sdk-core",
+    "version": "0.2.0-beta.3",
+    "contractPath": "contracts/v0.2.0-beta.3/sdk-parity.json"
+  },
+  "sha256": "61b49a71457190173ee749e9603f5a7f8f226caabf6ad0a8fa94a66b683c4ec9",
+  "source": {
+    "repository": "https://github.com/mitralab-dev/mitra-core-sdk",
+    "commit": "dd0aa46c5b3e5c7ea0a907355f428b1963a95e8b",
+    "path": "contracts/v0.2.0-beta.3/sdk-parity.json"
+  }
+}

package/dist/index.cjs

@@ -30,13 +30,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  AgentTaskTurnError: () => import_sdk_core3.AgentTaskTurnError,
+  AgentTaskTurnError: () => import_sdk_core4.AgentTaskTurnError,
   MitraApiError: () => MitraApiError,
   MitraConfigurationError: () => MitraConfigurationError,
   callIntegrationMitra: () => callIntegrationMitra2,
   configureSdkMitra: () => configureSdkMitra3,
   createAgentMitra: () => createAgentMitra2,
   createClient: () => createClient,
+  createClientFromApiKey: () => createClientFromApiKey,
   createClientFromEnvironment: () => createClientFromEnvironment,
   createIntegrationMitra: () => createIntegrationMitra2,
   createJdbcConnectionMitra: () => createJdbcConnectionMitra2,
@@ -100,7 +101,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var import_sdk_core2 = require("@mitralab.io/sdk-core");
+var import_sdk_core3 = require("@mitralab.io/sdk-core");
 
 // src/agent-task-sse.ts
 var import_sdk_core = require("@mitralab.io/sdk-core");
@@ -213,9 +214,13 @@ function createApiError(response, payload, accessToken) {
     ...retryable === void 0 ? {} : { retryable }
   });
 }
+function isUnauthorized(error) {
+  return error instanceof MitraApiError && error.status === 401;
+}
 var HttpClient = class {
   #authentication;
   #accessToken;
+  #tokenProvider;
   baseUrl;
   appId;
   timeoutMs;
@@ -224,21 +229,28 @@ var HttpClient = class {
     this.baseUrl = config.baseUrl;
     this.#authentication = config.authentication;
     this.#accessToken = config.authentication === "bearer" ? config.accessToken : void 0;
+    this.#tokenProvider = config.authentication === "bearer" ? config.tokenProvider : void 0;
     this.appId = config.authentication === "bearer" ? config.appId : void 0;
     this.timeoutMs = config.timeoutMs;
     this.fetchImplementation = config.fetch;
   }
   async request(path, options = {}) {
+    try {
+      return await this.attempt(path, options);
+    } catch (error) {
+      if (this.#tokenProvider === void 0 || !isUnauthorized(error)) throw error;
+      this.#tokenProvider.invalidate();
+      return this.attempt(path, options);
+    }
+  }
+  async attempt(path, options) {
     const url = new URL(`${this.baseUrl}${path}`);
     appendQueryParameters(url, options.params ?? {});
     const controller = this.timeoutMs === void 0 ? void 0 : new AbortController();
     const timeout = controller === void 0 ? void 0 : setTimeout(() => controller.abort(), this.timeoutMs);
     const hasBody = options.body !== void 0;
-    const authentication = this.#authentication === "bearer" ? {
-      type: "bearer",
-      accessToken: this.#accessToken,
-      appId: this.appId
-    } : { type: "anonymous" };
+    const accessToken = this.#authentication === "bearer" ? await this.#tokenProvider?.get() ?? this.#accessToken : void 0;
+    const authentication = accessToken === void 0 ? { type: "anonymous" } : { type: "bearer", accessToken, appId: this.appId };
     try {
       const response = await this.fetchImplementation(url, {
         method: options.method ?? "GET",
@@ -249,7 +261,7 @@ var HttpClient = class {
       });
       if (response.status === 204) return void 0;
       const payload = await parsePayload(response);
-      if (!response.ok) throw createApiError(response, payload, this.#accessToken);
+      if (!response.ok) throw createApiError(response, payload, accessToken);
       return payload;
     } catch (error) {
       if (error instanceof MitraApiError) throw error;
@@ -550,6 +562,75 @@ function createAppScopedAppsModule(apps, appId) {
   };
 }
 
+// src/api-key.ts
+var import_sdk_core2 = require("@mitralab.io/sdk-core");
+
+// src/core-errors.ts
+var coreErrors = {
+  configuration: (message) => new MitraConfigurationError(message),
+  invalidResponse: (message) => new MitraApiError(message, 200, { code: "INVALID_RESPONSE", retryable: false })
+};
+
+// src/api-key.ts
+var EXPIRY_SKEW_MS = 5 * 60 * 1e3;
+var IAM_BASE = "/iam";
+async function exchangeApiKey(options) {
+  const { apiUrl, apiKey, appId, fetch: fetchImplementation } = options;
+  return (0, import_sdk_core2.resolveApiKeyToken)(
+    async (path, init) => {
+      const response = await fetchImplementation(new URL(`${apiUrl}${IAM_BASE}${path}`), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...init.bearer === void 0 ? {} : { Authorization: `Bearer ${init.bearer}` }
+        },
+        ...init.body === void 0 ? {} : { body: JSON.stringify(init.body) },
+        redirect: "manual"
+      });
+      if (!response.ok) {
+        throw new MitraApiError(
+          `Api key authentication failed with status ${response.status}`,
+          response.status,
+          {
+            code: response.status === 401 ? "INVALID_CREDENTIALS" : "AUTHENTICATION_FAILED",
+            retryable: response.status >= 500
+          }
+        );
+      }
+      return response.json();
+    },
+    appId,
+    apiKey,
+    coreErrors
+  );
+}
+function createApiKeyTokenProvider(options) {
+  if (!options.apiKey.trim()) {
+    throw new MitraConfigurationError("apiKey must not be empty");
+  }
+  let token = null;
+  let renewAfter = 0;
+  let pending = null;
+  return {
+    async get() {
+      if (token !== null && Date.now() < renewAfter) return token;
+      pending ??= exchangeApiKey(options).then((fresh) => {
+        const expiry = (0, import_sdk_core2.readTokenExpiry)(fresh);
+        token = fresh;
+        renewAfter = expiry === null ? Number.MAX_SAFE_INTEGER : expiry - EXPIRY_SKEW_MS;
+        return fresh;
+      }).finally(() => {
+        pending = null;
+      });
+      return pending;
+    },
+    invalidate() {
+      token = null;
+      renewAfter = 0;
+    }
+  };
+}
+
 // src/config.ts
 function readDefaultEnvironment() {
   return typeof process === "undefined" ? {} : process.env;
@@ -588,6 +669,26 @@ function deriveNativeApiUrl(legacyBaseUrl) {
   parsed.pathname = parsed.pathname.replace(/\/legacy\/?$/, "") || "/";
   return removeTrailingSlashes(parsed.toString());
 }
+function resolveApiKeyOptions(config = {}, environment = readDefaultEnvironment()) {
+  const fetchImplementation = config.fetch ?? globalThis.fetch;
+  if (typeof fetchImplementation !== "function") {
+    throw new MitraConfigurationError("A fetch implementation is required");
+  }
+  return {
+    apiUrl: normalizeApiUrl(
+      requiredValue(
+        config.apiUrl ?? environment.MITRA_API_URL ?? deriveNativeApiUrl(environment.MITRA_BASE_URL),
+        "apiUrl"
+      )
+    ),
+    appId: requiredValue(
+      config.appId ?? environment.MITRA_APP_ID ?? environment.MITRA_PROJECT_ID,
+      "appId"
+    ),
+    apiKey: requiredValue(config.apiKey ?? environment.MITRA_API_KEY, "apiKey"),
+    fetch: fetchImplementation
+  };
+}
 function resolveConfig(config = {}, environment = readDefaultEnvironment()) {
   const apiUrl = normalizeApiUrl(
     requiredValue(
@@ -637,10 +738,6 @@ function configureLegacySdk(config) {
 }
 
 // src/client.ts
-var coreErrors = {
-  configuration: (message) => new MitraConfigurationError(message),
-  invalidResponse: (message) => new MitraApiError(message, 200, { code: "INVALID_RESPONSE", retryable: false })
-};
 var DefaultMitraClient = class {
   agentConnections;
   agentCredentials;
@@ -679,10 +776,11 @@ var DefaultMitraClient = class {
       authentication: "bearer",
       accessToken: config.accessToken,
       appId: config.appId,
+      ...config.tokenProvider === void 0 ? {} : { tokenProvider: config.tokenProvider },
       ...config.timeoutMs === void 0 ? {} : { timeoutMs: config.timeoutMs },
       fetch: config.fetch
     });
-    const core = (0, import_sdk_core2.createSdkCore)({
+    const core = (0, import_sdk_core3.createSdkCore)({
       transports: {
         auth: httpClient("iam"),
         codeStudio: httpClient("code-studio"),
@@ -706,7 +804,7 @@ var DefaultMitraClient = class {
     this.agentConnections = core.agentConnections;
     this.agentCredentials = core.agentCredentials;
     this.agents = core.agents;
-    const agentSessionManager = (0, import_sdk_core2.createAgentTaskSessionManager)({
+    const agentSessionManager = (0, import_sdk_core3.createAgentTaskSessionManager)({
       tasks: core.agentTasks,
       eventSource: new AgentTaskSseEventSource({
         baseUrl: `${config.apiUrl}/copilot`,
@@ -717,7 +815,7 @@ var DefaultMitraClient = class {
         errors: coreErrors
       })
     });
-    this.agentTasks = (0, import_sdk_core2.withAgentTaskSessions)(core.agentTasks, {
+    this.agentTasks = (0, import_sdk_core3.withAgentTaskSessions)(core.agentTasks, {
       session: (options) => {
         if (options.transport === "websocket") {
           throw new MitraConfigurationError(
@@ -761,9 +859,9 @@ var DefaultMitraClient = class {
     return this.#initPromise;
   }
   async resolveDataSourceId() {
-    const appInfo = (0, import_sdk_core2.expectObject)(
+    const appInfo = (0, import_sdk_core3.expectObject)(
       await this.#codeStudioHttpClient.get(
-        `/api/v1/apps/${(0, import_sdk_core2.encodePathSegment)(this.#appId, "appId", coreErrors)}/info`
+        `/api/v1/apps/${(0, import_sdk_core3.encodePathSegment)(this.#appId, "appId", coreErrors)}/info`
       ),
       "App info response",
       coreErrors
@@ -788,9 +886,18 @@ function createClient(config = {}) {
 function createClientFromEnvironment(environment) {
   return createConfiguredClient(resolveConfig({}, environment));
 }
+async function createClientFromApiKey(config = {}, environment) {
+  const options = resolveApiKeyOptions(config, environment);
+  const tokenProvider = createApiKeyTokenProvider(options);
+  const accessToken = await tokenProvider.get();
+  return createConfiguredClient({
+    ...resolveConfig({ ...config, accessToken, appId: options.appId }, environment),
+    tokenProvider
+  });
+}
 
 // src/index.ts
-var import_sdk_core3 = require("@mitralab.io/sdk-core");
+var import_sdk_core4 = require("@mitralab.io/sdk-core");
 
 // src/legacy/index.ts
 var legacy = __toESM(require("mitra-sdk"), 1);
@@ -864,6 +971,7 @@ var getDeployStatusMitra2 = legacy.getDeployStatusMitra;
   configureSdkMitra,
   createAgentMitra,
   createClient,
+  createClientFromApiKey,
   createClientFromEnvironment,
   createIntegrationMitra,
   createJdbcConnectionMitra,

package/dist/index.d.cts

@@ -27,6 +27,8 @@ type Fetch = typeof globalThis.fetch;
 interface MitraEnvironment {
     MITRA_API_URL?: string;
     MITRA_PLATFORM_ACCESS_TOKEN?: string;
+    /** Api key created in Settings -> API keys. Traded for a token by the SDK. */
+    MITRA_API_KEY?: string;
     MITRA_APP_ID?: string;
     MITRA_DATA_SOURCE_ID?: string;
     /** Existing Server Function base URL. Used to derive the native API root when needed. */
@@ -42,6 +44,8 @@ interface MitraClientConfig {
     /** Optional BFF base URL used only to configure deprecated reexports. */
     legacyBaseUrl?: string;
     accessToken?: string;
+    /** Api key created in Settings -> API keys, used by `createClientFromApiKey`. */
+    apiKey?: string;
     appId?: string;
     dataSourceId?: string;
     /** Optional request deadline. By default, the Functions runtime owns operation time limits. */
@@ -79,6 +83,19 @@ interface MitraClient {
 }
 declare function createClient(config?: MitraClientConfig): MitraClient;
 declare function createClientFromEnvironment(environment?: MitraEnvironment): MitraClient;
+/**
+ * Builds a client that authenticates with an api key instead of a token you already hold.
+ *
+ * The key is traded for a token here and again whenever that token ages out, so a process
+ * that stays up for days keeps working. Reads `MITRA_API_KEY` when `apiKey` is omitted.
+ */
+declare function createClientFromApiKey(config?: MitraClientConfig, environment?: MitraEnvironment): Promise<MitraClient>;
+
+/** Resolves the bearer token for each request, renewing it when it expires. */
+interface AccessTokenProvider {
+    get(): Promise<string>;
+    invalidate(): void;
+}
 
 declare class MitraConfigurationError extends Error {
     constructor(message: string);
@@ -1023,4 +1040,4 @@ type GetDeployStatusOptions = legacy.GetDeployStatusOptions;
  */
 type GetDeployStatusResponse = legacy.GetDeployStatusResponse;
 
-export { type Agent, type AgentChat, type AgentConnection, type AgentCredentialStatus, type AgentDeltaEvent, type AgentErrorEvent, type AgentMessage, type AgentModel, type AgentProvider, type AgentQueueChangeEvent, type AgentRawEvent, type AgentStatusChangeEvent, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentTaskTransport, type AgentTimelineItem, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AppScopedAppsModule, type AuthAgentCredentialResult, type AuthorizationConfig, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialResult, type ConnectorTemplateResponse, type CreateAgentOptions, type CreateAgentResponse, type CreateIntegrationOptions, type CreateJdbcConnectionOptions, type CreateJdbcConnectionResponse, type CreateOnlineTableOptions, type CreateOnlineTableResponse, type CreateProjectOptions, type CreateProjectResponse, type CreateRecordOptions, type CreateRecordsBatchOptions, type CreateServerFunctionOptions, type CreateServerFunctionResponse, type CredentialAction, type CurrentAppModule, type DeleteAgentChatResult, type DeleteAgentOptions, type DeleteAgentResponse, type DeleteIntegrationOptions, type DeleteJdbcConnectionOptions, type DeleteJdbcConnectionResponse, type DeleteOnlineTableOptions, type DeleteOnlineTableResponse, type DeleteRecordOptions, type DeleteServerFunctionOptions, type DeleteServerFunctionResponse, type DeployToS3Options, type DeployToS3Response, type DeviceAuthAgentCredentialResult, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type Fetch, type GetAgentTaskCreateOptions, type GetAgentTaskOpenOptions, type GetAgentTaskOptions, type GetDeployStatusOptions, type GetDeployStatusResponse, type GetGitConfigOptions, type GetGitConfigResponse, type GetIntegrationTemplateOptions, type GetProjectContextOptions, type GetProjectContextResponse, type GetProjectsResponse, type GetRecordOptions, type GetServerFunctionExecutionOptions, type GetServerFunctionExecutionResponse, type IntegrationResponse, type InviteUserOptions, type InviteUserResult, type ListAgentConnectionsResult, type ListAgentModelsResult, type ListAgentProvidersResult, type ListAgentsOptions, type ListAgentsResponse, type ListIntegrationTemplatesOptions, type ListIntegrationsOptions, type ListJdbcConnectionsOptions, type ListJdbcConnectionsResponse, type ListOnlineTablesOptions, type ListOnlineTablesResponse, type ListProjectsOptions, type ListProjectsResponse, type ListRecordsOptions, type ListRecordsResponse, type ListServerFunctionsOptions, type ListServerFunctionsResponse, type ListTablesOptions, type ListTablesResponse, type ManageAgentChatDeleteOptions, type ManageAgentChatListOptions, type ManageAgentChatOptions, type ManageAgentChatRenameOptions, type ManageAgentConnectionOptions, type ManageAgentCredentialOptions, MitraApiError, type MitraClient, type MitraClientConfig, type MitraConfig, MitraConfigurationError, type MitraEnvironment, type MitraSdkInstance, type PatchRecordOptions, type QueuedItem, type ReadAgentOptions, type ReadAgentResponse, type ReadServerFunctionOptions, type ReadServerFunctionResponse, type RenameAgentChatResult, type RunDdlOptions, type RunDdlResponse, type RunDmlOptions, type RunDmlResponse, type RunQueryOptions, type RunQueryResponse, type SendOptions, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type TemplateField, type TestConnectionResponse, type TestIntegrationByIdOptions, type TestIntegrationOptions, type TogglePublicExecutionOptions, type TogglePublicExecutionResponse, type UnsubscribeUserOptions, type UnsubscribeUserResult, type UpdateAgentOptions, type UpdateAgentResponse, type UpdateIntegrationOptions, type UpdateJdbcConnectionOptions, type UpdateJdbcConnectionResponse, type UpdateOnlineTableOptions, type UpdateOnlineTableResponse, type UpdateProjectSettingsOptions, type UpdateProjectSettingsResponse, type UpdateRecordOptions, type UpdateServerFunctionOptions, type UpdateServerFunctionResponse, callIntegrationMitra, configureSdkMitra, createAgentMitra, createClient, createClientFromEnvironment, createIntegrationMitra, createJdbcConnectionMitra, createMitraSdkInstance, createOnlineTableMitra, createProjectMitra, createRecordMitra, createRecordsBatchMitra, createServerFunctionMitra, deleteAgentMitra, deleteIntegrationMitra, deleteJdbcConnectionMitra, deleteOnlineTableMitra, deleteRecordMitra, deleteServerFunctionMitra, deployToS3Mitra, executePublicServerFunctionAsyncMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getAgentTaskMitra, getDeployStatusMitra, getGitConfigMitra, getIntegrationTemplateMitra, getProjectContextMitra, getProjectsMitra, getRecordMitra, getServerFunctionExecutionMitra, inviteUserMitra, listAgentsMitra, listIntegrationTemplatesMitra, listIntegrationsMitra, listJdbcConnectionsMitra, listOnlineTablesMitra, listProjectsMitra, listRecordsMitra, listServerFunctionsMitra, listTablesMitra, manageAgentChatMitra, manageAgentConnectionMitra, manageAgentCredentialMitra, patchRecordMitra, readAgentMitra, readServerFunctionMitra, resolveProjectId, runDdlMitra, runDmlMitra, runQueryMitra, stopServerFunctionExecutionMitra, testIntegrationByIdMitra, testIntegrationMitra, togglePublicExecutionMitra, unsubscribeUserMitra, updateAgentMitra, updateIntegrationMitra, updateJdbcConnectionMitra, updateOnlineTableMitra, updateProjectSettingsMitra, updateRecordMitra, updateServerFunctionMitra };
+export { type AccessTokenProvider, type Agent, type AgentChat, type AgentConnection, type AgentCredentialStatus, type AgentDeltaEvent, type AgentErrorEvent, type AgentMessage, type AgentModel, type AgentProvider, type AgentQueueChangeEvent, type AgentRawEvent, type AgentStatusChangeEvent, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentTaskTransport, type AgentTimelineItem, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AppScopedAppsModule, type AuthAgentCredentialResult, type AuthorizationConfig, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialResult, type ConnectorTemplateResponse, type CreateAgentOptions, type CreateAgentResponse, type CreateIntegrationOptions, type CreateJdbcConnectionOptions, type CreateJdbcConnectionResponse, type CreateOnlineTableOptions, type CreateOnlineTableResponse, type CreateProjectOptions, type CreateProjectResponse, type CreateRecordOptions, type CreateRecordsBatchOptions, type CreateServerFunctionOptions, type CreateServerFunctionResponse, type CredentialAction, type CurrentAppModule, type DeleteAgentChatResult, type DeleteAgentOptions, type DeleteAgentResponse, type DeleteIntegrationOptions, type DeleteJdbcConnectionOptions, type DeleteJdbcConnectionResponse, type DeleteOnlineTableOptions, type DeleteOnlineTableResponse, type DeleteRecordOptions, type DeleteServerFunctionOptions, type DeleteServerFunctionResponse, type DeployToS3Options, type DeployToS3Response, type DeviceAuthAgentCredentialResult, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type Fetch, type GetAgentTaskCreateOptions, type GetAgentTaskOpenOptions, type GetAgentTaskOptions, type GetDeployStatusOptions, type GetDeployStatusResponse, type GetGitConfigOptions, type GetGitConfigResponse, type GetIntegrationTemplateOptions, type GetProjectContextOptions, type GetProjectContextResponse, type GetProjectsResponse, type GetRecordOptions, type GetServerFunctionExecutionOptions, type GetServerFunctionExecutionResponse, type IntegrationResponse, type InviteUserOptions, type InviteUserResult, type ListAgentConnectionsResult, type ListAgentModelsResult, type ListAgentProvidersResult, type ListAgentsOptions, type ListAgentsResponse, type ListIntegrationTemplatesOptions, type ListIntegrationsOptions, type ListJdbcConnectionsOptions, type ListJdbcConnectionsResponse, type ListOnlineTablesOptions, type ListOnlineTablesResponse, type ListProjectsOptions, type ListProjectsResponse, type ListRecordsOptions, type ListRecordsResponse, type ListServerFunctionsOptions, type ListServerFunctionsResponse, type ListTablesOptions, type ListTablesResponse, type ManageAgentChatDeleteOptions, type ManageAgentChatListOptions, type ManageAgentChatOptions, type ManageAgentChatRenameOptions, type ManageAgentConnectionOptions, type ManageAgentCredentialOptions, MitraApiError, type MitraClient, type MitraClientConfig, type MitraConfig, MitraConfigurationError, type MitraEnvironment, type MitraSdkInstance, type PatchRecordOptions, type QueuedItem, type ReadAgentOptions, type ReadAgentResponse, type ReadServerFunctionOptions, type ReadServerFunctionResponse, type RenameAgentChatResult, type RunDdlOptions, type RunDdlResponse, type RunDmlOptions, type RunDmlResponse, type RunQueryOptions, type RunQueryResponse, type SendOptions, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type TemplateField, type TestConnectionResponse, type TestIntegrationByIdOptions, type TestIntegrationOptions, type TogglePublicExecutionOptions, type TogglePublicExecutionResponse, type UnsubscribeUserOptions, type UnsubscribeUserResult, type UpdateAgentOptions, type UpdateAgentResponse, type UpdateIntegrationOptions, type UpdateJdbcConnectionOptions, type UpdateJdbcConnectionResponse, type UpdateOnlineTableOptions, type UpdateOnlineTableResponse, type UpdateProjectSettingsOptions, type UpdateProjectSettingsResponse, type UpdateRecordOptions, type UpdateServerFunctionOptions, type UpdateServerFunctionResponse, callIntegrationMitra, configureSdkMitra, createAgentMitra, createClient, createClientFromApiKey, createClientFromEnvironment, createIntegrationMitra, createJdbcConnectionMitra, createMitraSdkInstance, createOnlineTableMitra, createProjectMitra, createRecordMitra, createRecordsBatchMitra, createServerFunctionMitra, deleteAgentMitra, deleteIntegrationMitra, deleteJdbcConnectionMitra, deleteOnlineTableMitra, deleteRecordMitra, deleteServerFunctionMitra, deployToS3Mitra, executePublicServerFunctionAsyncMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getAgentTaskMitra, getDeployStatusMitra, getGitConfigMitra, getIntegrationTemplateMitra, getProjectContextMitra, getProjectsMitra, getRecordMitra, getServerFunctionExecutionMitra, inviteUserMitra, listAgentsMitra, listIntegrationTemplatesMitra, listIntegrationsMitra, listJdbcConnectionsMitra, listOnlineTablesMitra, listProjectsMitra, listRecordsMitra, listServerFunctionsMitra, listTablesMitra, manageAgentChatMitra, manageAgentConnectionMitra, manageAgentCredentialMitra, patchRecordMitra, readAgentMitra, readServerFunctionMitra, resolveProjectId, runDdlMitra, runDmlMitra, runQueryMitra, stopServerFunctionExecutionMitra, testIntegrationByIdMitra, testIntegrationMitra, togglePublicExecutionMitra, unsubscribeUserMitra, updateAgentMitra, updateIntegrationMitra, updateJdbcConnectionMitra, updateOnlineTableMitra, updateProjectSettingsMitra, updateRecordMitra, updateServerFunctionMitra };

package/dist/index.d.ts

@@ -27,6 +27,8 @@ type Fetch = typeof globalThis.fetch;
 interface MitraEnvironment {
     MITRA_API_URL?: string;
     MITRA_PLATFORM_ACCESS_TOKEN?: string;
+    /** Api key created in Settings -> API keys. Traded for a token by the SDK. */
+    MITRA_API_KEY?: string;
     MITRA_APP_ID?: string;
     MITRA_DATA_SOURCE_ID?: string;
     /** Existing Server Function base URL. Used to derive the native API root when needed. */
@@ -42,6 +44,8 @@ interface MitraClientConfig {
     /** Optional BFF base URL used only to configure deprecated reexports. */
     legacyBaseUrl?: string;
     accessToken?: string;
+    /** Api key created in Settings -> API keys, used by `createClientFromApiKey`. */
+    apiKey?: string;
     appId?: string;
     dataSourceId?: string;
     /** Optional request deadline. By default, the Functions runtime owns operation time limits. */
@@ -79,6 +83,19 @@ interface MitraClient {
 }
 declare function createClient(config?: MitraClientConfig): MitraClient;
 declare function createClientFromEnvironment(environment?: MitraEnvironment): MitraClient;
+/**
+ * Builds a client that authenticates with an api key instead of a token you already hold.
+ *
+ * The key is traded for a token here and again whenever that token ages out, so a process
+ * that stays up for days keeps working. Reads `MITRA_API_KEY` when `apiKey` is omitted.
+ */
+declare function createClientFromApiKey(config?: MitraClientConfig, environment?: MitraEnvironment): Promise<MitraClient>;
+
+/** Resolves the bearer token for each request, renewing it when it expires. */
+interface AccessTokenProvider {
+    get(): Promise<string>;
+    invalidate(): void;
+}
 
 declare class MitraConfigurationError extends Error {
     constructor(message: string);
@@ -1023,4 +1040,4 @@ type GetDeployStatusOptions = legacy.GetDeployStatusOptions;
  */
 type GetDeployStatusResponse = legacy.GetDeployStatusResponse;
 
-export { type Agent, type AgentChat, type AgentConnection, type AgentCredentialStatus, type AgentDeltaEvent, type AgentErrorEvent, type AgentMessage, type AgentModel, type AgentProvider, type AgentQueueChangeEvent, type AgentRawEvent, type AgentStatusChangeEvent, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentTaskTransport, type AgentTimelineItem, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AppScopedAppsModule, type AuthAgentCredentialResult, type AuthorizationConfig, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialResult, type ConnectorTemplateResponse, type CreateAgentOptions, type CreateAgentResponse, type CreateIntegrationOptions, type CreateJdbcConnectionOptions, type CreateJdbcConnectionResponse, type CreateOnlineTableOptions, type CreateOnlineTableResponse, type CreateProjectOptions, type CreateProjectResponse, type CreateRecordOptions, type CreateRecordsBatchOptions, type CreateServerFunctionOptions, type CreateServerFunctionResponse, type CredentialAction, type CurrentAppModule, type DeleteAgentChatResult, type DeleteAgentOptions, type DeleteAgentResponse, type DeleteIntegrationOptions, type DeleteJdbcConnectionOptions, type DeleteJdbcConnectionResponse, type DeleteOnlineTableOptions, type DeleteOnlineTableResponse, type DeleteRecordOptions, type DeleteServerFunctionOptions, type DeleteServerFunctionResponse, type DeployToS3Options, type DeployToS3Response, type DeviceAuthAgentCredentialResult, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type Fetch, type GetAgentTaskCreateOptions, type GetAgentTaskOpenOptions, type GetAgentTaskOptions, type GetDeployStatusOptions, type GetDeployStatusResponse, type GetGitConfigOptions, type GetGitConfigResponse, type GetIntegrationTemplateOptions, type GetProjectContextOptions, type GetProjectContextResponse, type GetProjectsResponse, type GetRecordOptions, type GetServerFunctionExecutionOptions, type GetServerFunctionExecutionResponse, type IntegrationResponse, type InviteUserOptions, type InviteUserResult, type ListAgentConnectionsResult, type ListAgentModelsResult, type ListAgentProvidersResult, type ListAgentsOptions, type ListAgentsResponse, type ListIntegrationTemplatesOptions, type ListIntegrationsOptions, type ListJdbcConnectionsOptions, type ListJdbcConnectionsResponse, type ListOnlineTablesOptions, type ListOnlineTablesResponse, type ListProjectsOptions, type ListProjectsResponse, type ListRecordsOptions, type ListRecordsResponse, type ListServerFunctionsOptions, type ListServerFunctionsResponse, type ListTablesOptions, type ListTablesResponse, type ManageAgentChatDeleteOptions, type ManageAgentChatListOptions, type ManageAgentChatOptions, type ManageAgentChatRenameOptions, type ManageAgentConnectionOptions, type ManageAgentCredentialOptions, MitraApiError, type MitraClient, type MitraClientConfig, type MitraConfig, MitraConfigurationError, type MitraEnvironment, type MitraSdkInstance, type PatchRecordOptions, type QueuedItem, type ReadAgentOptions, type ReadAgentResponse, type ReadServerFunctionOptions, type ReadServerFunctionResponse, type RenameAgentChatResult, type RunDdlOptions, type RunDdlResponse, type RunDmlOptions, type RunDmlResponse, type RunQueryOptions, type RunQueryResponse, type SendOptions, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type TemplateField, type TestConnectionResponse, type TestIntegrationByIdOptions, type TestIntegrationOptions, type TogglePublicExecutionOptions, type TogglePublicExecutionResponse, type UnsubscribeUserOptions, type UnsubscribeUserResult, type UpdateAgentOptions, type UpdateAgentResponse, type UpdateIntegrationOptions, type UpdateJdbcConnectionOptions, type UpdateJdbcConnectionResponse, type UpdateOnlineTableOptions, type UpdateOnlineTableResponse, type UpdateProjectSettingsOptions, type UpdateProjectSettingsResponse, type UpdateRecordOptions, type UpdateServerFunctionOptions, type UpdateServerFunctionResponse, callIntegrationMitra, configureSdkMitra, createAgentMitra, createClient, createClientFromEnvironment, createIntegrationMitra, createJdbcConnectionMitra, createMitraSdkInstance, createOnlineTableMitra, createProjectMitra, createRecordMitra, createRecordsBatchMitra, createServerFunctionMitra, deleteAgentMitra, deleteIntegrationMitra, deleteJdbcConnectionMitra, deleteOnlineTableMitra, deleteRecordMitra, deleteServerFunctionMitra, deployToS3Mitra, executePublicServerFunctionAsyncMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getAgentTaskMitra, getDeployStatusMitra, getGitConfigMitra, getIntegrationTemplateMitra, getProjectContextMitra, getProjectsMitra, getRecordMitra, getServerFunctionExecutionMitra, inviteUserMitra, listAgentsMitra, listIntegrationTemplatesMitra, listIntegrationsMitra, listJdbcConnectionsMitra, listOnlineTablesMitra, listProjectsMitra, listRecordsMitra, listServerFunctionsMitra, listTablesMitra, manageAgentChatMitra, manageAgentConnectionMitra, manageAgentCredentialMitra, patchRecordMitra, readAgentMitra, readServerFunctionMitra, resolveProjectId, runDdlMitra, runDmlMitra, runQueryMitra, stopServerFunctionExecutionMitra, testIntegrationByIdMitra, testIntegrationMitra, togglePublicExecutionMitra, unsubscribeUserMitra, updateAgentMitra, updateIntegrationMitra, updateJdbcConnectionMitra, updateOnlineTableMitra, updateProjectSettingsMitra, updateRecordMitra, updateServerFunctionMitra };
+export { type AccessTokenProvider, type Agent, type AgentChat, type AgentConnection, type AgentCredentialStatus, type AgentDeltaEvent, type AgentErrorEvent, type AgentMessage, type AgentModel, type AgentProvider, type AgentQueueChangeEvent, type AgentRawEvent, type AgentStatusChangeEvent, type AgentTaskCreatedEvent, type AgentTaskEventMap, type AgentTaskEventName, type AgentTaskSession, type AgentTaskStatus, type AgentTaskTransport, type AgentTimelineItem, type AgentToolEvent, type AgentTurnEndEvent, type AgentType, type AppScopedAppsModule, type AuthAgentCredentialResult, type AuthorizationConfig, type CallIntegrationOptions, type CallIntegrationResponse, type ChatManageAction, type ConnectAgentCredentialResult, type ConnectorTemplateResponse, type CreateAgentOptions, type CreateAgentResponse, type CreateIntegrationOptions, type CreateJdbcConnectionOptions, type CreateJdbcConnectionResponse, type CreateOnlineTableOptions, type CreateOnlineTableResponse, type CreateProjectOptions, type CreateProjectResponse, type CreateRecordOptions, type CreateRecordsBatchOptions, type CreateServerFunctionOptions, type CreateServerFunctionResponse, type CredentialAction, type CurrentAppModule, type DeleteAgentChatResult, type DeleteAgentOptions, type DeleteAgentResponse, type DeleteIntegrationOptions, type DeleteJdbcConnectionOptions, type DeleteJdbcConnectionResponse, type DeleteOnlineTableOptions, type DeleteOnlineTableResponse, type DeleteRecordOptions, type DeleteServerFunctionOptions, type DeleteServerFunctionResponse, type DeployToS3Options, type DeployToS3Response, type DeviceAuthAgentCredentialResult, type ExecutePublicServerFunctionAsyncResponse, type ExecutePublicServerFunctionOptions, type ExecuteServerFunctionAsyncOptions, type ExecuteServerFunctionAsyncResponse, type ExecuteServerFunctionOptions, type ExecuteServerFunctionResponse, type Fetch, type GetAgentTaskCreateOptions, type GetAgentTaskOpenOptions, type GetAgentTaskOptions, type GetDeployStatusOptions, type GetDeployStatusResponse, type GetGitConfigOptions, type GetGitConfigResponse, type GetIntegrationTemplateOptions, type GetProjectContextOptions, type GetProjectContextResponse, type GetProjectsResponse, type GetRecordOptions, type GetServerFunctionExecutionOptions, type GetServerFunctionExecutionResponse, type IntegrationResponse, type InviteUserOptions, type InviteUserResult, type ListAgentConnectionsResult, type ListAgentModelsResult, type ListAgentProvidersResult, type ListAgentsOptions, type ListAgentsResponse, type ListIntegrationTemplatesOptions, type ListIntegrationsOptions, type ListJdbcConnectionsOptions, type ListJdbcConnectionsResponse, type ListOnlineTablesOptions, type ListOnlineTablesResponse, type ListProjectsOptions, type ListProjectsResponse, type ListRecordsOptions, type ListRecordsResponse, type ListServerFunctionsOptions, type ListServerFunctionsResponse, type ListTablesOptions, type ListTablesResponse, type ManageAgentChatDeleteOptions, type ManageAgentChatListOptions, type ManageAgentChatOptions, type ManageAgentChatRenameOptions, type ManageAgentConnectionOptions, type ManageAgentCredentialOptions, MitraApiError, type MitraClient, type MitraClientConfig, type MitraConfig, MitraConfigurationError, type MitraEnvironment, type MitraSdkInstance, type PatchRecordOptions, type QueuedItem, type ReadAgentOptions, type ReadAgentResponse, type ReadServerFunctionOptions, type ReadServerFunctionResponse, type RenameAgentChatResult, type RunDdlOptions, type RunDdlResponse, type RunDmlOptions, type RunDmlResponse, type RunQueryOptions, type RunQueryResponse, type SendOptions, type StopServerFunctionExecutionOptions, type StopServerFunctionExecutionResponse, type TemplateField, type TestConnectionResponse, type TestIntegrationByIdOptions, type TestIntegrationOptions, type TogglePublicExecutionOptions, type TogglePublicExecutionResponse, type UnsubscribeUserOptions, type UnsubscribeUserResult, type UpdateAgentOptions, type UpdateAgentResponse, type UpdateIntegrationOptions, type UpdateJdbcConnectionOptions, type UpdateJdbcConnectionResponse, type UpdateOnlineTableOptions, type UpdateOnlineTableResponse, type UpdateProjectSettingsOptions, type UpdateProjectSettingsResponse, type UpdateRecordOptions, type UpdateServerFunctionOptions, type UpdateServerFunctionResponse, callIntegrationMitra, configureSdkMitra, createAgentMitra, createClient, createClientFromApiKey, createClientFromEnvironment, createIntegrationMitra, createJdbcConnectionMitra, createMitraSdkInstance, createOnlineTableMitra, createProjectMitra, createRecordMitra, createRecordsBatchMitra, createServerFunctionMitra, deleteAgentMitra, deleteIntegrationMitra, deleteJdbcConnectionMitra, deleteOnlineTableMitra, deleteRecordMitra, deleteServerFunctionMitra, deployToS3Mitra, executePublicServerFunctionAsyncMitra, executeServerFunctionAsyncMitra, executeServerFunctionMitra, getAgentTaskMitra, getDeployStatusMitra, getGitConfigMitra, getIntegrationTemplateMitra, getProjectContextMitra, getProjectsMitra, getRecordMitra, getServerFunctionExecutionMitra, inviteUserMitra, listAgentsMitra, listIntegrationTemplatesMitra, listIntegrationsMitra, listJdbcConnectionsMitra, listOnlineTablesMitra, listProjectsMitra, listRecordsMitra, listServerFunctionsMitra, listTablesMitra, manageAgentChatMitra, manageAgentConnectionMitra, manageAgentCredentialMitra, patchRecordMitra, readAgentMitra, readServerFunctionMitra, resolveProjectId, runDdlMitra, runDmlMitra, runQueryMitra, stopServerFunctionExecutionMitra, testIntegrationByIdMitra, testIntegrationMitra, togglePublicExecutionMitra, unsubscribeUserMitra, updateAgentMitra, updateIntegrationMitra, updateJdbcConnectionMitra, updateOnlineTableMitra, updateProjectSettingsMitra, updateRecordMitra, updateServerFunctionMitra };

package/dist/index.js

@@ -120,9 +120,13 @@ function createApiError(response, payload, accessToken) {
     ...retryable === void 0 ? {} : { retryable }
   });
 }
+function isUnauthorized(error) {
+  return error instanceof MitraApiError && error.status === 401;
+}
 var HttpClient = class {
   #authentication;
   #accessToken;
+  #tokenProvider;
   baseUrl;
   appId;
   timeoutMs;
@@ -131,21 +135,28 @@ var HttpClient = class {
     this.baseUrl = config.baseUrl;
     this.#authentication = config.authentication;
     this.#accessToken = config.authentication === "bearer" ? config.accessToken : void 0;
+    this.#tokenProvider = config.authentication === "bearer" ? config.tokenProvider : void 0;
     this.appId = config.authentication === "bearer" ? config.appId : void 0;
     this.timeoutMs = config.timeoutMs;
     this.fetchImplementation = config.fetch;
   }
   async request(path, options = {}) {
+    try {
+      return await this.attempt(path, options);
+    } catch (error) {
+      if (this.#tokenProvider === void 0 || !isUnauthorized(error)) throw error;
+      this.#tokenProvider.invalidate();
+      return this.attempt(path, options);
+    }
+  }
+  async attempt(path, options) {
     const url = new URL(`${this.baseUrl}${path}`);
     appendQueryParameters(url, options.params ?? {});
     const controller = this.timeoutMs === void 0 ? void 0 : new AbortController();
     const timeout = controller === void 0 ? void 0 : setTimeout(() => controller.abort(), this.timeoutMs);
     const hasBody = options.body !== void 0;
-    const authentication = this.#authentication === "bearer" ? {
-      type: "bearer",
-      accessToken: this.#accessToken,
-      appId: this.appId
-    } : { type: "anonymous" };
+    const accessToken = this.#authentication === "bearer" ? await this.#tokenProvider?.get() ?? this.#accessToken : void 0;
+    const authentication = accessToken === void 0 ? { type: "anonymous" } : { type: "bearer", accessToken, appId: this.appId };
     try {
       const response = await this.fetchImplementation(url, {
         method: options.method ?? "GET",
@@ -156,7 +167,7 @@ var HttpClient = class {
       });
       if (response.status === 204) return void 0;
       const payload = await parsePayload(response);
-      if (!response.ok) throw createApiError(response, payload, this.#accessToken);
+      if (!response.ok) throw createApiError(response, payload, accessToken);
       return payload;
     } catch (error) {
       if (error instanceof MitraApiError) throw error;
@@ -457,6 +468,75 @@ function createAppScopedAppsModule(apps, appId) {
   };
 }
 
+// src/api-key.ts
+import { readTokenExpiry, resolveApiKeyToken } from "@mitralab.io/sdk-core";
+
+// src/core-errors.ts
+var coreErrors = {
+  configuration: (message) => new MitraConfigurationError(message),
+  invalidResponse: (message) => new MitraApiError(message, 200, { code: "INVALID_RESPONSE", retryable: false })
+};
+
+// src/api-key.ts
+var EXPIRY_SKEW_MS = 5 * 60 * 1e3;
+var IAM_BASE = "/iam";
+async function exchangeApiKey(options) {
+  const { apiUrl, apiKey, appId, fetch: fetchImplementation } = options;
+  return resolveApiKeyToken(
+    async (path, init) => {
+      const response = await fetchImplementation(new URL(`${apiUrl}${IAM_BASE}${path}`), {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...init.bearer === void 0 ? {} : { Authorization: `Bearer ${init.bearer}` }
+        },
+        ...init.body === void 0 ? {} : { body: JSON.stringify(init.body) },
+        redirect: "manual"
+      });
+      if (!response.ok) {
+        throw new MitraApiError(
+          `Api key authentication failed with status ${response.status}`,
+          response.status,
+          {
+            code: response.status === 401 ? "INVALID_CREDENTIALS" : "AUTHENTICATION_FAILED",
+            retryable: response.status >= 500
+          }
+        );
+      }
+      return response.json();
+    },
+    appId,
+    apiKey,
+    coreErrors
+  );
+}
+function createApiKeyTokenProvider(options) {
+  if (!options.apiKey.trim()) {
+    throw new MitraConfigurationError("apiKey must not be empty");
+  }
+  let token = null;
+  let renewAfter = 0;
+  let pending = null;
+  return {
+    async get() {
+      if (token !== null && Date.now() < renewAfter) return token;
+      pending ??= exchangeApiKey(options).then((fresh) => {
+        const expiry = readTokenExpiry(fresh);
+        token = fresh;
+        renewAfter = expiry === null ? Number.MAX_SAFE_INTEGER : expiry - EXPIRY_SKEW_MS;
+        return fresh;
+      }).finally(() => {
+        pending = null;
+      });
+      return pending;
+    },
+    invalidate() {
+      token = null;
+      renewAfter = 0;
+    }
+  };
+}
+
 // src/config.ts
 function readDefaultEnvironment() {
   return typeof process === "undefined" ? {} : process.env;
@@ -495,6 +575,26 @@ function deriveNativeApiUrl(legacyBaseUrl) {
   parsed.pathname = parsed.pathname.replace(/\/legacy\/?$/, "") || "/";
   return removeTrailingSlashes(parsed.toString());
 }
+function resolveApiKeyOptions(config = {}, environment = readDefaultEnvironment()) {
+  const fetchImplementation = config.fetch ?? globalThis.fetch;
+  if (typeof fetchImplementation !== "function") {
+    throw new MitraConfigurationError("A fetch implementation is required");
+  }
+  return {
+    apiUrl: normalizeApiUrl(
+      requiredValue(
+        config.apiUrl ?? environment.MITRA_API_URL ?? deriveNativeApiUrl(environment.MITRA_BASE_URL),
+        "apiUrl"
+      )
+    ),
+    appId: requiredValue(
+      config.appId ?? environment.MITRA_APP_ID ?? environment.MITRA_PROJECT_ID,
+      "appId"
+    ),
+    apiKey: requiredValue(config.apiKey ?? environment.MITRA_API_KEY, "apiKey"),
+    fetch: fetchImplementation
+  };
+}
 function resolveConfig(config = {}, environment = readDefaultEnvironment()) {
   const apiUrl = normalizeApiUrl(
     requiredValue(
@@ -544,10 +644,6 @@ function configureLegacySdk(config) {
 }
 
 // src/client.ts
-var coreErrors = {
-  configuration: (message) => new MitraConfigurationError(message),
-  invalidResponse: (message) => new MitraApiError(message, 200, { code: "INVALID_RESPONSE", retryable: false })
-};
 var DefaultMitraClient = class {
   agentConnections;
   agentCredentials;
@@ -586,6 +682,7 @@ var DefaultMitraClient = class {
       authentication: "bearer",
       accessToken: config.accessToken,
       appId: config.appId,
+      ...config.tokenProvider === void 0 ? {} : { tokenProvider: config.tokenProvider },
       ...config.timeoutMs === void 0 ? {} : { timeoutMs: config.timeoutMs },
       fetch: config.fetch
     });
@@ -695,6 +792,15 @@ function createClient(config = {}) {
 function createClientFromEnvironment(environment) {
   return createConfiguredClient(resolveConfig({}, environment));
 }
+async function createClientFromApiKey(config = {}, environment) {
+  const options = resolveApiKeyOptions(config, environment);
+  const tokenProvider = createApiKeyTokenProvider(options);
+  const accessToken = await tokenProvider.get();
+  return createConfiguredClient({
+    ...resolveConfig({ ...config, accessToken, appId: options.appId }, environment),
+    tokenProvider
+  });
+}
 
 // src/index.ts
 import { AgentTaskTurnError } from "@mitralab.io/sdk-core";
@@ -770,6 +876,7 @@ export {
   configureSdkMitra3 as configureSdkMitra,
   createAgentMitra2 as createAgentMitra,
   createClient,
+  createClientFromApiKey,
   createClientFromEnvironment,
   createIntegrationMitra2 as createIntegrationMitra,
   createJdbcConnectionMitra2 as createJdbcConnectionMitra,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitralab.io/functions-sdk",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.2",
   "description": "JavaScript and TypeScript SDK for Mitra Server Functions",
   "type": "module",
   "sideEffects": false,
@@ -67,7 +67,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@mitralab.io/sdk-core": "0.2.0-beta.1",
+    "@mitralab.io/sdk-core": "0.2.0-beta.3",
     "mitra-sdk": "1.0.63-beta.42"
   },
   "devDependencies": {