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

package/dist/index.cjs

@@ -20,9 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  API_KEY_EXCHANGE_PATH: () => API_KEY_EXCHANGE_PATH,
   AgentTaskTurnError: () => AgentTaskTurnError,
   SdkCoreConfigurationError: () => SdkCoreConfigurationError,
   SdkCoreResponseError: () => SdkCoreResponseError,
+  appAccessTokenPath: () => appAccessTokenPath,
   createAgentConnectionsModule: () => createAgentConnectionsModule,
   createAgentCredentialsModule: () => createAgentCredentialsModule,
   createAgentTaskSessionManager: () => createAgentTaskSessionManager,
@@ -58,7 +60,12 @@ __export(index_exports, {
   expectObjectArray: () => expectObjectArray,
   expectPage: () => expectPage,
   expectStringArray: () => expectStringArray,
+  isWorkspaceSession: () => isWorkspaceSession,
+  readTokenAppId: () => readTokenAppId,
+  readTokenExpiry: () => readTokenExpiry,
+  resolveApiKeyToken: () => resolveApiKeyToken,
   toAgentTimelineItem: () => toAgentTimelineItem,
+  tokenAuthorizesApp: () => tokenAuthorizesApp,
   withAgentTaskSessions: () => withAgentTaskSessions
 });
 module.exports = __toCommonJS(index_exports);
@@ -3694,11 +3701,80 @@ var CoreAgentTaskSession = class {
     }
   }
 };
+
+// src/apiKeySession.ts
+var API_KEY_EXCHANGE_PATH = "/api/v1/auth/exchange";
+function appAccessTokenPath(appId) {
+  return `/api/v1/auth/apps/${encodeURIComponent(appId)}/access-token`;
+}
+function decodeTokenPayload(token) {
+  const segment = token.split(".")[1];
+  if (!segment || typeof globalThis.atob !== "function") return null;
+  try {
+    const base64 = segment.replaceAll("-", "+").replaceAll("_", "/");
+    const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+    const decoded = JSON.parse(globalThis.atob(padded));
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+function readTokenAppId(token) {
+  const appId = decodeTokenPayload(token)?.app_id;
+  return typeof appId === "string" && appId ? appId : null;
+}
+function readTokenExpiry(token) {
+  const exp = decodeTokenPayload(token)?.exp;
+  return typeof exp === "number" && Number.isFinite(exp) ? exp * 1e3 : null;
+}
+function tokenAuthorizesApp(token, appId) {
+  const payload = decodeTokenPayload(token);
+  if (!payload) return true;
+  return payload.app_id === appId;
+}
+function isWorkspaceSession(token) {
+  const payload = decodeTokenPayload(token);
+  return payload !== null && payload.app_id === void 0;
+}
+function readAccessToken(payload, operation, errors) {
+  const token = payload && typeof payload === "object" ? payload.accessToken : void 0;
+  if (typeof token !== "string" || !token.trim()) {
+    throw errors.invalidResponse(`The ${operation} response did not include an access token`);
+  }
+  return token;
+}
+async function resolveApiKeyToken(call, appId, apiKey, errors = defaultSdkCoreErrorFactory) {
+  if (!apiKey.trim()) {
+    throw errors.configuration("An api key is required to authenticate with an api key");
+  }
+  if (!appId.trim()) {
+    throw errors.configuration("An app id is required to authenticate with an api key");
+  }
+  const exchanged = readAccessToken(
+    await call(API_KEY_EXCHANGE_PATH, { body: { apiKey } }),
+    "api key exchange",
+    errors
+  );
+  if (tokenAuthorizesApp(exchanged, appId)) return exchanged;
+  if (!isWorkspaceSession(exchanged)) {
+    throw errors.configuration(
+      `This api key belongs to app ${readTokenAppId(exchanged) ?? "unknown"}, not to ${appId}. Create the key for this app, or use a workspace key.`
+    );
+  }
+  return readAccessToken(
+    await call(appAccessTokenPath(appId), { bearer: exchanged }),
+    "app token",
+    errors
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  API_KEY_EXCHANGE_PATH,
   AgentTaskTurnError,
   SdkCoreConfigurationError,
   SdkCoreResponseError,
+  appAccessTokenPath,
   createAgentConnectionsModule,
   createAgentCredentialsModule,
   createAgentTaskSessionManager,
@@ -3734,6 +3810,11 @@ var CoreAgentTaskSession = class {
   expectObjectArray,
   expectPage,
   expectStringArray,
+  isWorkspaceSession,
+  readTokenAppId,
+  readTokenExpiry,
+  resolveApiKeyToken,
   toAgentTimelineItem,
+  tokenAuthorizesApp,
   withAgentTaskSessions
 });

package/dist/index.d.cts

@@ -1846,6 +1846,50 @@ declare function toAgentTimelineItem(message: AgentMessage): AgentTimelineItem;
 declare function createAgentTaskSessionManager(options: AgentTaskSessionManagerOptions): AgentTaskSessionManager;
 declare function withAgentTaskSessions(tasks: AgentTasksModule, manager: AgentTaskSessionManager): AgentTasksWithSessions;
 
+/**
+ * What the SDKs have to know about trading an api key for a token.
+ *
+ * The knowledge lives here rather than in each SDK because it is a contract with IAM, not a
+ * utility: which claim names the app, what the exchange answers, and when a token still needs
+ * a second call before it authorizes anything. When IAM changes any of that, it changes once.
+ *
+ * This module makes no HTTP call of its own — this package defines `Transport`, it does not
+ * implement one. The caller performs the request and keeps whatever belongs to it: caching,
+ * renewal, its own error type, its own runtime guards.
+ */
+/** IAM path, relative to the service root, that trades an api key for a token. */
+declare const API_KEY_EXCHANGE_PATH = "/api/v1/auth/exchange";
+/** IAM path, relative to the service root, that issues an app token from a workspace session. */
+declare function appAccessTokenPath(appId: string): string;
+/** Performs one POST against IAM and returns the parsed body. */
+type ApiKeyExchangeCaller = (path: string, init: {
+    body?: unknown;
+    bearer?: string;
+}) => Promise<unknown>;
+/** The app a token authorizes, or `null` for a workspace session and for anything unreadable. */
+declare function readTokenAppId(token: string): string | null;
+/** When a token stops being accepted, in milliseconds, or `null` when it cannot be read. */
+declare function readTokenExpiry(token: string): number | null;
+/**
+ * Whether a token already authorizes `appId`.
+ *
+ * An unreadable token counts as authorized: the platform is the authority on a token it
+ * issued, and refusing one the SDK merely failed to parse would break a caller for no reason.
+ */
+declare function tokenAuthorizesApp(token: string, appId: string): boolean;
+/** Whether a token is a workspace session, the only kind an app token can be issued from. */
+declare function isWorkspaceSession(token: string): boolean;
+/**
+ * Trades an api key for a token that authorizes `appId`.
+ *
+ * A Developer or Business key belongs to a product, so the exchange already answers with that
+ * product's token. An Administrator key belongs to a workspace: the exchange answers with a
+ * workspace session, and the app token is issued from it. That second call is where the
+ * platform decides what the key's owner actually reaches in this product, which is why a
+ * workspace key never turns into blanket access.
+ */
+declare function resolveApiKeyToken(call: ApiKeyExchangeCaller, appId: string, apiKey: string, errors?: SdkCoreErrorFactory): Promise<string>;
+
 declare function encodePathSegment(value: string | number, name: string, errors?: SdkCoreErrorFactory): string;
 
 declare function expectObject<T extends object>(value: unknown, context: string, errors?: SdkCoreErrorFactory): T;
@@ -1856,4 +1900,4 @@ declare function expectPage<T extends object>(value: unknown, context: string, e
 declare function expectLegacyPage<T extends object>(value: unknown, context: string, errors?: SdkCoreErrorFactory, validateItem?: (value: unknown, context: string, errors: SdkCoreErrorFactory) => T): LegacyPage<T>;
 declare function expectEmpty(value: unknown, context: string, errors?: SdkCoreErrorFactory): void;
 
-export { type AgentBulkDeleteResult, type AgentConnection, type AgentConnectionCreateInput, type AgentConnectionsModule, type AgentCredentialsModule, type AgentDefinition, type AgentInput, type AgentMessage, type AgentModel, type AgentQueueItem, type AgentSendAndWaitOptions, type AgentSendOptions, type AgentSessionTransport, type AgentTask, type AgentTaskCreateInput, type AgentTaskEvent, type AgentTaskEventConnection, type AgentTaskEventObserver, type AgentTaskEventSource, type AgentTaskInput, type AgentTaskListOptions, type AgentTaskSession, type AgentTaskSessionEventMap, type AgentTaskSessionManager, type AgentTaskSessionManagerOptions, type AgentTaskSessionOptions, type AgentTaskSessionStatus, AgentTaskTurnError, type AgentTasksModule, type AgentTasksWithSessions, type AgentTimelineItem, type AgentToolEvent, type AgentTurnResult, type AgentUpdateItem, type AgentsModule, type AppColor, type AppContext, type AppCreateInput, type AppDefinition, type AppDeploy, type AppDomain, type AppFiles, type AppGetOptions, type AppListOptions, type AppMember, type AppPublishOptions, type AppSummary, type AppUpdateInput, type AppVersion, type AppVersionStatus, type AppsModule, type AuthModule, type AuthenticationResult, type BatchExecution, type BatchStatementResult, type BulkUnsubscribeResult, type ColumnInput, type ConnectionConfig, type ConnectionConfigResponse, type ConnectionTestResult, type ContextModule, type ContextModuleDependencies, type CopilotProvider, type CredentialStatus, type CustomQueriesModule, type CustomQueryDefinition, type CustomQueryInput, type CustomQuerySummary, type CustomQueryUpdateInput, type DataSourceBulkItemResult, type DataSourceBulkResult, type DataSourceCreateInput, type DataSourceDbType, type DataSourceDefinition, type DataSourceInstanceType, type DataSourceUpdateInput, type DataSourcesModule, type DdlStatement, type DeviceAuthorization, type DmlStatement, type EmptyFunctionInput, type EntitiesModule, type EntitiesProxy, type EntityListOptions, type EntityListResponse, type EntityTable, type ExistingAgentTaskSessionOptions, type FunctionBulkCreateInput, type FunctionBulkDeleteInput, type FunctionBulkDeleteResult, type FunctionBulkPatchInput, type FunctionBulkPatchItem, type FunctionBulkUpdateItem, type FunctionCreateInput, type FunctionDefinition, type FunctionExecution, type FunctionListOptions, type FunctionPatchInput, type FunctionRuntime, type FunctionSecrets, type FunctionSummary, type FunctionUpdateInput, type FunctionVersion, type FunctionVersionListOptions, type FunctionVisibility, type FunctionsAdminModule, type FunctionsModule, type FunctionsModuleOptions, type HttpMethod, type ImportColumnMapping, type ImportDefinition, type ImportExecution, type ImportExecutionListOptions, type ImportInput, type ImportProcessing, type ImportSchedule, type ImportSource, type ImportSourceResponse, type ImportTarget, type ImportsModule, type IntegrationAdminModule, type IntegrationConnectionStatus, type IntegrationCredentialRule, type IntegrationExecution, type IntegrationFieldSchema, type IntegrationFieldSchemaInput, type IntegrationLoginConfig, type IntegrationModule, type IntegrationProxyMode, type IntegrationRequestConfig, type IntegrationResource, type IntegrationResourceInput, type IntegrationResourceParam, type IntegrationResourceSummary, type IntegrationResourceUpdateInput, type IntegrationResourcesModule, type IntegrationTemplate, type IntegrationTemplateSummary, type IntegrationTemplateType, type IntegrationTemplatesModule, type IntegrationTokenExtraction, type InviteAppUserInput, type InvocationType, type JsonValue, type LegacyPage, type ListTablesOptions, type ListTemplateConfigsOptions, type MembersModule, type MessageAccepted, type MessengerModule, type NewAgentTaskSessionOptions, type OAuthExchangeInput, type OAuthStartResult, type Page, type PageOptions, type PlanPrice, type ProviderCredentialStatus, type ProxyInput, type ProxyResult, type PublicFunctionAsyncResult, type PublicFunctionResult, type PublicFunctionsModule, type QueriesModule, type QueryParamPrimitive, type QueryParamValue, type QueryResult, type SchemaModule, type SchemaScope, type SchemaTables, type SdkCore, SdkCoreConfigurationError, type SdkCoreErrorFactory, type SdkCoreOptions, SdkCoreResponseError, type SdkCoreTransports, type SqlModule, type TableColumn, type TableDefinition, type TableForeignKey, type TemplateConfig, type TemplateConfigBulkItemResult, type TemplateConfigBulkResult, type TemplateConfigCreateInput, type TemplateConfigPage, type TemplateConfigSummary, type TemplateConfigUpdateInput, type Tenant, type TestCredentialsInput, type Transport, type TransportRequestOptions, type User, type UserPlan, type WorkflowDefinition, type WorkflowExecution, type WorkflowInput, type WorkflowSummary, type WorkflowsModule, createAgentConnectionsModule, createAgentCredentialsModule, createAgentTaskSessionManager, createAgentTasksModule, createAgentsModule, createAppsModule, createAuthModule, createContextModule, createCustomQueriesModule, createDataSourcesModule, createEntitiesModule, createFunctionsAdminModule, createFunctionsModule, createImportsModule, createIntegrationAdminModule, createIntegrationModule, createIntegrationResourcesModule, createIntegrationTemplatesModule, createMembersModule, createMessengerModule, createPublicFunctionsModule, createQueriesModule, createSchemaModule, createSdkCore, createSqlModule, createWorkflowsModule, defaultSdkCoreErrorFactory, encodePathSegment, expectEmpty, expectLegacyPage, expectNullableObject, expectObject, expectObjectArray, expectPage, expectStringArray, toAgentTimelineItem, withAgentTaskSessions };
+export { API_KEY_EXCHANGE_PATH, type AgentBulkDeleteResult, type AgentConnection, type AgentConnectionCreateInput, type AgentConnectionsModule, type AgentCredentialsModule, type AgentDefinition, type AgentInput, type AgentMessage, type AgentModel, type AgentQueueItem, type AgentSendAndWaitOptions, type AgentSendOptions, type AgentSessionTransport, type AgentTask, type AgentTaskCreateInput, type AgentTaskEvent, type AgentTaskEventConnection, type AgentTaskEventObserver, type AgentTaskEventSource, type AgentTaskInput, type AgentTaskListOptions, type AgentTaskSession, type AgentTaskSessionEventMap, type AgentTaskSessionManager, type AgentTaskSessionManagerOptions, type AgentTaskSessionOptions, type AgentTaskSessionStatus, AgentTaskTurnError, type AgentTasksModule, type AgentTasksWithSessions, type AgentTimelineItem, type AgentToolEvent, type AgentTurnResult, type AgentUpdateItem, type AgentsModule, type ApiKeyExchangeCaller, type AppColor, type AppContext, type AppCreateInput, type AppDefinition, type AppDeploy, type AppDomain, type AppFiles, type AppGetOptions, type AppListOptions, type AppMember, type AppPublishOptions, type AppSummary, type AppUpdateInput, type AppVersion, type AppVersionStatus, type AppsModule, type AuthModule, type AuthenticationResult, type BatchExecution, type BatchStatementResult, type BulkUnsubscribeResult, type ColumnInput, type ConnectionConfig, type ConnectionConfigResponse, type ConnectionTestResult, type ContextModule, type ContextModuleDependencies, type CopilotProvider, type CredentialStatus, type CustomQueriesModule, type CustomQueryDefinition, type CustomQueryInput, type CustomQuerySummary, type CustomQueryUpdateInput, type DataSourceBulkItemResult, type DataSourceBulkResult, type DataSourceCreateInput, type DataSourceDbType, type DataSourceDefinition, type DataSourceInstanceType, type DataSourceUpdateInput, type DataSourcesModule, type DdlStatement, type DeviceAuthorization, type DmlStatement, type EmptyFunctionInput, type EntitiesModule, type EntitiesProxy, type EntityListOptions, type EntityListResponse, type EntityTable, type ExistingAgentTaskSessionOptions, type FunctionBulkCreateInput, type FunctionBulkDeleteInput, type FunctionBulkDeleteResult, type FunctionBulkPatchInput, type FunctionBulkPatchItem, type FunctionBulkUpdateItem, type FunctionCreateInput, type FunctionDefinition, type FunctionExecution, type FunctionListOptions, type FunctionPatchInput, type FunctionRuntime, type FunctionSecrets, type FunctionSummary, type FunctionUpdateInput, type FunctionVersion, type FunctionVersionListOptions, type FunctionVisibility, type FunctionsAdminModule, type FunctionsModule, type FunctionsModuleOptions, type HttpMethod, type ImportColumnMapping, type ImportDefinition, type ImportExecution, type ImportExecutionListOptions, type ImportInput, type ImportProcessing, type ImportSchedule, type ImportSource, type ImportSourceResponse, type ImportTarget, type ImportsModule, type IntegrationAdminModule, type IntegrationConnectionStatus, type IntegrationCredentialRule, type IntegrationExecution, type IntegrationFieldSchema, type IntegrationFieldSchemaInput, type IntegrationLoginConfig, type IntegrationModule, type IntegrationProxyMode, type IntegrationRequestConfig, type IntegrationResource, type IntegrationResourceInput, type IntegrationResourceParam, type IntegrationResourceSummary, type IntegrationResourceUpdateInput, type IntegrationResourcesModule, type IntegrationTemplate, type IntegrationTemplateSummary, type IntegrationTemplateType, type IntegrationTemplatesModule, type IntegrationTokenExtraction, type InviteAppUserInput, type InvocationType, type JsonValue, type LegacyPage, type ListTablesOptions, type ListTemplateConfigsOptions, type MembersModule, type MessageAccepted, type MessengerModule, type NewAgentTaskSessionOptions, type OAuthExchangeInput, type OAuthStartResult, type Page, type PageOptions, type PlanPrice, type ProviderCredentialStatus, type ProxyInput, type ProxyResult, type PublicFunctionAsyncResult, type PublicFunctionResult, type PublicFunctionsModule, type QueriesModule, type QueryParamPrimitive, type QueryParamValue, type QueryResult, type SchemaModule, type SchemaScope, type SchemaTables, type SdkCore, SdkCoreConfigurationError, type SdkCoreErrorFactory, type SdkCoreOptions, SdkCoreResponseError, type SdkCoreTransports, type SqlModule, type TableColumn, type TableDefinition, type TableForeignKey, type TemplateConfig, type TemplateConfigBulkItemResult, type TemplateConfigBulkResult, type TemplateConfigCreateInput, type TemplateConfigPage, type TemplateConfigSummary, type TemplateConfigUpdateInput, type Tenant, type TestCredentialsInput, type Transport, type TransportRequestOptions, type User, type UserPlan, type WorkflowDefinition, type WorkflowExecution, type WorkflowInput, type WorkflowSummary, type WorkflowsModule, appAccessTokenPath, createAgentConnectionsModule, createAgentCredentialsModule, createAgentTaskSessionManager, createAgentTasksModule, createAgentsModule, createAppsModule, createAuthModule, createContextModule, createCustomQueriesModule, createDataSourcesModule, createEntitiesModule, createFunctionsAdminModule, createFunctionsModule, createImportsModule, createIntegrationAdminModule, createIntegrationModule, createIntegrationResourcesModule, createIntegrationTemplatesModule, createMembersModule, createMessengerModule, createPublicFunctionsModule, createQueriesModule, createSchemaModule, createSdkCore, createSqlModule, createWorkflowsModule, defaultSdkCoreErrorFactory, encodePathSegment, expectEmpty, expectLegacyPage, expectNullableObject, expectObject, expectObjectArray, expectPage, expectStringArray, isWorkspaceSession, readTokenAppId, readTokenExpiry, resolveApiKeyToken, toAgentTimelineItem, tokenAuthorizesApp, withAgentTaskSessions };

package/dist/index.d.ts

@@ -1846,6 +1846,50 @@ declare function toAgentTimelineItem(message: AgentMessage): AgentTimelineItem;
 declare function createAgentTaskSessionManager(options: AgentTaskSessionManagerOptions): AgentTaskSessionManager;
 declare function withAgentTaskSessions(tasks: AgentTasksModule, manager: AgentTaskSessionManager): AgentTasksWithSessions;
 
+/**
+ * What the SDKs have to know about trading an api key for a token.
+ *
+ * The knowledge lives here rather than in each SDK because it is a contract with IAM, not a
+ * utility: which claim names the app, what the exchange answers, and when a token still needs
+ * a second call before it authorizes anything. When IAM changes any of that, it changes once.
+ *
+ * This module makes no HTTP call of its own — this package defines `Transport`, it does not
+ * implement one. The caller performs the request and keeps whatever belongs to it: caching,
+ * renewal, its own error type, its own runtime guards.
+ */
+/** IAM path, relative to the service root, that trades an api key for a token. */
+declare const API_KEY_EXCHANGE_PATH = "/api/v1/auth/exchange";
+/** IAM path, relative to the service root, that issues an app token from a workspace session. */
+declare function appAccessTokenPath(appId: string): string;
+/** Performs one POST against IAM and returns the parsed body. */
+type ApiKeyExchangeCaller = (path: string, init: {
+    body?: unknown;
+    bearer?: string;
+}) => Promise<unknown>;
+/** The app a token authorizes, or `null` for a workspace session and for anything unreadable. */
+declare function readTokenAppId(token: string): string | null;
+/** When a token stops being accepted, in milliseconds, or `null` when it cannot be read. */
+declare function readTokenExpiry(token: string): number | null;
+/**
+ * Whether a token already authorizes `appId`.
+ *
+ * An unreadable token counts as authorized: the platform is the authority on a token it
+ * issued, and refusing one the SDK merely failed to parse would break a caller for no reason.
+ */
+declare function tokenAuthorizesApp(token: string, appId: string): boolean;
+/** Whether a token is a workspace session, the only kind an app token can be issued from. */
+declare function isWorkspaceSession(token: string): boolean;
+/**
+ * Trades an api key for a token that authorizes `appId`.
+ *
+ * A Developer or Business key belongs to a product, so the exchange already answers with that
+ * product's token. An Administrator key belongs to a workspace: the exchange answers with a
+ * workspace session, and the app token is issued from it. That second call is where the
+ * platform decides what the key's owner actually reaches in this product, which is why a
+ * workspace key never turns into blanket access.
+ */
+declare function resolveApiKeyToken(call: ApiKeyExchangeCaller, appId: string, apiKey: string, errors?: SdkCoreErrorFactory): Promise<string>;
+
 declare function encodePathSegment(value: string | number, name: string, errors?: SdkCoreErrorFactory): string;
 
 declare function expectObject<T extends object>(value: unknown, context: string, errors?: SdkCoreErrorFactory): T;
@@ -1856,4 +1900,4 @@ declare function expectPage<T extends object>(value: unknown, context: string, e
 declare function expectLegacyPage<T extends object>(value: unknown, context: string, errors?: SdkCoreErrorFactory, validateItem?: (value: unknown, context: string, errors: SdkCoreErrorFactory) => T): LegacyPage<T>;
 declare function expectEmpty(value: unknown, context: string, errors?: SdkCoreErrorFactory): void;
 
-export { type AgentBulkDeleteResult, type AgentConnection, type AgentConnectionCreateInput, type AgentConnectionsModule, type AgentCredentialsModule, type AgentDefinition, type AgentInput, type AgentMessage, type AgentModel, type AgentQueueItem, type AgentSendAndWaitOptions, type AgentSendOptions, type AgentSessionTransport, type AgentTask, type AgentTaskCreateInput, type AgentTaskEvent, type AgentTaskEventConnection, type AgentTaskEventObserver, type AgentTaskEventSource, type AgentTaskInput, type AgentTaskListOptions, type AgentTaskSession, type AgentTaskSessionEventMap, type AgentTaskSessionManager, type AgentTaskSessionManagerOptions, type AgentTaskSessionOptions, type AgentTaskSessionStatus, AgentTaskTurnError, type AgentTasksModule, type AgentTasksWithSessions, type AgentTimelineItem, type AgentToolEvent, type AgentTurnResult, type AgentUpdateItem, type AgentsModule, type AppColor, type AppContext, type AppCreateInput, type AppDefinition, type AppDeploy, type AppDomain, type AppFiles, type AppGetOptions, type AppListOptions, type AppMember, type AppPublishOptions, type AppSummary, type AppUpdateInput, type AppVersion, type AppVersionStatus, type AppsModule, type AuthModule, type AuthenticationResult, type BatchExecution, type BatchStatementResult, type BulkUnsubscribeResult, type ColumnInput, type ConnectionConfig, type ConnectionConfigResponse, type ConnectionTestResult, type ContextModule, type ContextModuleDependencies, type CopilotProvider, type CredentialStatus, type CustomQueriesModule, type CustomQueryDefinition, type CustomQueryInput, type CustomQuerySummary, type CustomQueryUpdateInput, type DataSourceBulkItemResult, type DataSourceBulkResult, type DataSourceCreateInput, type DataSourceDbType, type DataSourceDefinition, type DataSourceInstanceType, type DataSourceUpdateInput, type DataSourcesModule, type DdlStatement, type DeviceAuthorization, type DmlStatement, type EmptyFunctionInput, type EntitiesModule, type EntitiesProxy, type EntityListOptions, type EntityListResponse, type EntityTable, type ExistingAgentTaskSessionOptions, type FunctionBulkCreateInput, type FunctionBulkDeleteInput, type FunctionBulkDeleteResult, type FunctionBulkPatchInput, type FunctionBulkPatchItem, type FunctionBulkUpdateItem, type FunctionCreateInput, type FunctionDefinition, type FunctionExecution, type FunctionListOptions, type FunctionPatchInput, type FunctionRuntime, type FunctionSecrets, type FunctionSummary, type FunctionUpdateInput, type FunctionVersion, type FunctionVersionListOptions, type FunctionVisibility, type FunctionsAdminModule, type FunctionsModule, type FunctionsModuleOptions, type HttpMethod, type ImportColumnMapping, type ImportDefinition, type ImportExecution, type ImportExecutionListOptions, type ImportInput, type ImportProcessing, type ImportSchedule, type ImportSource, type ImportSourceResponse, type ImportTarget, type ImportsModule, type IntegrationAdminModule, type IntegrationConnectionStatus, type IntegrationCredentialRule, type IntegrationExecution, type IntegrationFieldSchema, type IntegrationFieldSchemaInput, type IntegrationLoginConfig, type IntegrationModule, type IntegrationProxyMode, type IntegrationRequestConfig, type IntegrationResource, type IntegrationResourceInput, type IntegrationResourceParam, type IntegrationResourceSummary, type IntegrationResourceUpdateInput, type IntegrationResourcesModule, type IntegrationTemplate, type IntegrationTemplateSummary, type IntegrationTemplateType, type IntegrationTemplatesModule, type IntegrationTokenExtraction, type InviteAppUserInput, type InvocationType, type JsonValue, type LegacyPage, type ListTablesOptions, type ListTemplateConfigsOptions, type MembersModule, type MessageAccepted, type MessengerModule, type NewAgentTaskSessionOptions, type OAuthExchangeInput, type OAuthStartResult, type Page, type PageOptions, type PlanPrice, type ProviderCredentialStatus, type ProxyInput, type ProxyResult, type PublicFunctionAsyncResult, type PublicFunctionResult, type PublicFunctionsModule, type QueriesModule, type QueryParamPrimitive, type QueryParamValue, type QueryResult, type SchemaModule, type SchemaScope, type SchemaTables, type SdkCore, SdkCoreConfigurationError, type SdkCoreErrorFactory, type SdkCoreOptions, SdkCoreResponseError, type SdkCoreTransports, type SqlModule, type TableColumn, type TableDefinition, type TableForeignKey, type TemplateConfig, type TemplateConfigBulkItemResult, type TemplateConfigBulkResult, type TemplateConfigCreateInput, type TemplateConfigPage, type TemplateConfigSummary, type TemplateConfigUpdateInput, type Tenant, type TestCredentialsInput, type Transport, type TransportRequestOptions, type User, type UserPlan, type WorkflowDefinition, type WorkflowExecution, type WorkflowInput, type WorkflowSummary, type WorkflowsModule, createAgentConnectionsModule, createAgentCredentialsModule, createAgentTaskSessionManager, createAgentTasksModule, createAgentsModule, createAppsModule, createAuthModule, createContextModule, createCustomQueriesModule, createDataSourcesModule, createEntitiesModule, createFunctionsAdminModule, createFunctionsModule, createImportsModule, createIntegrationAdminModule, createIntegrationModule, createIntegrationResourcesModule, createIntegrationTemplatesModule, createMembersModule, createMessengerModule, createPublicFunctionsModule, createQueriesModule, createSchemaModule, createSdkCore, createSqlModule, createWorkflowsModule, defaultSdkCoreErrorFactory, encodePathSegment, expectEmpty, expectLegacyPage, expectNullableObject, expectObject, expectObjectArray, expectPage, expectStringArray, toAgentTimelineItem, withAgentTaskSessions };
+export { API_KEY_EXCHANGE_PATH, type AgentBulkDeleteResult, type AgentConnection, type AgentConnectionCreateInput, type AgentConnectionsModule, type AgentCredentialsModule, type AgentDefinition, type AgentInput, type AgentMessage, type AgentModel, type AgentQueueItem, type AgentSendAndWaitOptions, type AgentSendOptions, type AgentSessionTransport, type AgentTask, type AgentTaskCreateInput, type AgentTaskEvent, type AgentTaskEventConnection, type AgentTaskEventObserver, type AgentTaskEventSource, type AgentTaskInput, type AgentTaskListOptions, type AgentTaskSession, type AgentTaskSessionEventMap, type AgentTaskSessionManager, type AgentTaskSessionManagerOptions, type AgentTaskSessionOptions, type AgentTaskSessionStatus, AgentTaskTurnError, type AgentTasksModule, type AgentTasksWithSessions, type AgentTimelineItem, type AgentToolEvent, type AgentTurnResult, type AgentUpdateItem, type AgentsModule, type ApiKeyExchangeCaller, type AppColor, type AppContext, type AppCreateInput, type AppDefinition, type AppDeploy, type AppDomain, type AppFiles, type AppGetOptions, type AppListOptions, type AppMember, type AppPublishOptions, type AppSummary, type AppUpdateInput, type AppVersion, type AppVersionStatus, type AppsModule, type AuthModule, type AuthenticationResult, type BatchExecution, type BatchStatementResult, type BulkUnsubscribeResult, type ColumnInput, type ConnectionConfig, type ConnectionConfigResponse, type ConnectionTestResult, type ContextModule, type ContextModuleDependencies, type CopilotProvider, type CredentialStatus, type CustomQueriesModule, type CustomQueryDefinition, type CustomQueryInput, type CustomQuerySummary, type CustomQueryUpdateInput, type DataSourceBulkItemResult, type DataSourceBulkResult, type DataSourceCreateInput, type DataSourceDbType, type DataSourceDefinition, type DataSourceInstanceType, type DataSourceUpdateInput, type DataSourcesModule, type DdlStatement, type DeviceAuthorization, type DmlStatement, type EmptyFunctionInput, type EntitiesModule, type EntitiesProxy, type EntityListOptions, type EntityListResponse, type EntityTable, type ExistingAgentTaskSessionOptions, type FunctionBulkCreateInput, type FunctionBulkDeleteInput, type FunctionBulkDeleteResult, type FunctionBulkPatchInput, type FunctionBulkPatchItem, type FunctionBulkUpdateItem, type FunctionCreateInput, type FunctionDefinition, type FunctionExecution, type FunctionListOptions, type FunctionPatchInput, type FunctionRuntime, type FunctionSecrets, type FunctionSummary, type FunctionUpdateInput, type FunctionVersion, type FunctionVersionListOptions, type FunctionVisibility, type FunctionsAdminModule, type FunctionsModule, type FunctionsModuleOptions, type HttpMethod, type ImportColumnMapping, type ImportDefinition, type ImportExecution, type ImportExecutionListOptions, type ImportInput, type ImportProcessing, type ImportSchedule, type ImportSource, type ImportSourceResponse, type ImportTarget, type ImportsModule, type IntegrationAdminModule, type IntegrationConnectionStatus, type IntegrationCredentialRule, type IntegrationExecution, type IntegrationFieldSchema, type IntegrationFieldSchemaInput, type IntegrationLoginConfig, type IntegrationModule, type IntegrationProxyMode, type IntegrationRequestConfig, type IntegrationResource, type IntegrationResourceInput, type IntegrationResourceParam, type IntegrationResourceSummary, type IntegrationResourceUpdateInput, type IntegrationResourcesModule, type IntegrationTemplate, type IntegrationTemplateSummary, type IntegrationTemplateType, type IntegrationTemplatesModule, type IntegrationTokenExtraction, type InviteAppUserInput, type InvocationType, type JsonValue, type LegacyPage, type ListTablesOptions, type ListTemplateConfigsOptions, type MembersModule, type MessageAccepted, type MessengerModule, type NewAgentTaskSessionOptions, type OAuthExchangeInput, type OAuthStartResult, type Page, type PageOptions, type PlanPrice, type ProviderCredentialStatus, type ProxyInput, type ProxyResult, type PublicFunctionAsyncResult, type PublicFunctionResult, type PublicFunctionsModule, type QueriesModule, type QueryParamPrimitive, type QueryParamValue, type QueryResult, type SchemaModule, type SchemaScope, type SchemaTables, type SdkCore, SdkCoreConfigurationError, type SdkCoreErrorFactory, type SdkCoreOptions, SdkCoreResponseError, type SdkCoreTransports, type SqlModule, type TableColumn, type TableDefinition, type TableForeignKey, type TemplateConfig, type TemplateConfigBulkItemResult, type TemplateConfigBulkResult, type TemplateConfigCreateInput, type TemplateConfigPage, type TemplateConfigSummary, type TemplateConfigUpdateInput, type Tenant, type TestCredentialsInput, type Transport, type TransportRequestOptions, type User, type UserPlan, type WorkflowDefinition, type WorkflowExecution, type WorkflowInput, type WorkflowSummary, type WorkflowsModule, appAccessTokenPath, createAgentConnectionsModule, createAgentCredentialsModule, createAgentTaskSessionManager, createAgentTasksModule, createAgentsModule, createAppsModule, createAuthModule, createContextModule, createCustomQueriesModule, createDataSourcesModule, createEntitiesModule, createFunctionsAdminModule, createFunctionsModule, createImportsModule, createIntegrationAdminModule, createIntegrationModule, createIntegrationResourcesModule, createIntegrationTemplatesModule, createMembersModule, createMessengerModule, createPublicFunctionsModule, createQueriesModule, createSchemaModule, createSdkCore, createSqlModule, createWorkflowsModule, defaultSdkCoreErrorFactory, encodePathSegment, expectEmpty, expectLegacyPage, expectNullableObject, expectObject, expectObjectArray, expectPage, expectStringArray, isWorkspaceSession, readTokenAppId, readTokenExpiry, resolveApiKeyToken, toAgentTimelineItem, tokenAuthorizesApp, withAgentTaskSessions };

package/dist/index.js

@@ -3629,10 +3629,79 @@ var CoreAgentTaskSession = class {
     }
   }
 };
+
+// src/apiKeySession.ts
+var API_KEY_EXCHANGE_PATH = "/api/v1/auth/exchange";
+function appAccessTokenPath(appId) {
+  return `/api/v1/auth/apps/${encodeURIComponent(appId)}/access-token`;
+}
+function decodeTokenPayload(token) {
+  const segment = token.split(".")[1];
+  if (!segment || typeof globalThis.atob !== "function") return null;
+  try {
+    const base64 = segment.replaceAll("-", "+").replaceAll("_", "/");
+    const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+    const decoded = JSON.parse(globalThis.atob(padded));
+    if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+function readTokenAppId(token) {
+  const appId = decodeTokenPayload(token)?.app_id;
+  return typeof appId === "string" && appId ? appId : null;
+}
+function readTokenExpiry(token) {
+  const exp = decodeTokenPayload(token)?.exp;
+  return typeof exp === "number" && Number.isFinite(exp) ? exp * 1e3 : null;
+}
+function tokenAuthorizesApp(token, appId) {
+  const payload = decodeTokenPayload(token);
+  if (!payload) return true;
+  return payload.app_id === appId;
+}
+function isWorkspaceSession(token) {
+  const payload = decodeTokenPayload(token);
+  return payload !== null && payload.app_id === void 0;
+}
+function readAccessToken(payload, operation, errors) {
+  const token = payload && typeof payload === "object" ? payload.accessToken : void 0;
+  if (typeof token !== "string" || !token.trim()) {
+    throw errors.invalidResponse(`The ${operation} response did not include an access token`);
+  }
+  return token;
+}
+async function resolveApiKeyToken(call, appId, apiKey, errors = defaultSdkCoreErrorFactory) {
+  if (!apiKey.trim()) {
+    throw errors.configuration("An api key is required to authenticate with an api key");
+  }
+  if (!appId.trim()) {
+    throw errors.configuration("An app id is required to authenticate with an api key");
+  }
+  const exchanged = readAccessToken(
+    await call(API_KEY_EXCHANGE_PATH, { body: { apiKey } }),
+    "api key exchange",
+    errors
+  );
+  if (tokenAuthorizesApp(exchanged, appId)) return exchanged;
+  if (!isWorkspaceSession(exchanged)) {
+    throw errors.configuration(
+      `This api key belongs to app ${readTokenAppId(exchanged) ?? "unknown"}, not to ${appId}. Create the key for this app, or use a workspace key.`
+    );
+  }
+  return readAccessToken(
+    await call(appAccessTokenPath(appId), { bearer: exchanged }),
+    "app token",
+    errors
+  );
+}
 export {
+  API_KEY_EXCHANGE_PATH,
   AgentTaskTurnError,
   SdkCoreConfigurationError,
   SdkCoreResponseError,
+  appAccessTokenPath,
   createAgentConnectionsModule,
   createAgentCredentialsModule,
   createAgentTaskSessionManager,
@@ -3668,6 +3737,11 @@ export {
   expectObjectArray,
   expectPage,
   expectStringArray,
+  isWorkspaceSession,
+  readTokenAppId,
+  readTokenExpiry,
+  resolveApiKeyToken,
   toAgentTimelineItem,
+  tokenAuthorizesApp,
   withAgentTaskSessions
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitralab.io/sdk-core",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.2",
   "description": "Environment-neutral contracts and modules shared by Mitra JavaScript SDKs",
   "type": "module",
   "sideEffects": false,