@mitralab.io/functions-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## 0.1.0
+
+- Add environment-based Server Function client configuration.
+- Add current user, entity, custom query, Server Function, and integration APIs.
+- Add typed errors, request timeout, credential redaction, and package release automation.
+- Compose shared API contracts and modules from `@mitralab.io/sdk-core`.
+- Add commit- and digest-pinned SDK parity gates backed by the installed Core corpus.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitra Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# Mitra Functions SDK for JavaScript
+
+JavaScript and TypeScript SDK for code running inside Mitra Server Functions. It exposes the application-scoped Platform APIs that a function commonly needs without bringing browser authentication into the runtime.
+
+The SDK uses the short-lived platform access token injected into the function runtime. It does not log in users, persist credentials, refresh tokens, use API keys, or retry requests automatically.
+
+Shared API contracts and modules come from `@mitralab.io/sdk-core`. This package owns only the Server Function runtime adapter: environment configuration, token headers, timeout, credential redaction, redirect refusal, and one-attempt request policy. The core never receives or stores the token.
+
+## Installation
+
+```bash
+npm install @mitralab.io/functions-sdk
+```
+
+Node.js 18 or newer is required.
+
+## Runtime integration status
+
+The SDK is ready for the target runtime contract, but Functions and Sandbox do not inject it yet. Until that integration is delivered, these variables must be supplied explicitly in local or controlled execution environments:
+
+- `MITRA_API_URL`
+- `MITRA_PLATFORM_ACCESS_TOKEN`
+- `MITRA_APP_ID`
+- `MITRA_DATA_SOURCE_ID`, when already resolved by the runtime
+
+Do not treat user-defined function secrets as the runtime credential channel. The pending runtime integration must inject the platform access token separately from user secrets.
+
+## Quick start
+
+```typescript
+import { createClient } from "@mitralab.io/functions-sdk"
+
+const mitra = createClient()
+
+export async function handler(input: { orderId: string }) {
+  const order = await mitra.entities.Order.get(input.orderId)
+  return { order }
+}
+```
+
+Once the runtime integration is available, `createClient()` reads the process environment by default. For local development or explicit dependency injection, pass configuration directly:
+
+```typescript
+const mitra = createClient({
+  apiUrl: "https://api.example.com",
+  accessToken: process.env.MITRA_PLATFORM_ACCESS_TOKEN,
+  appId: "app-id",
+  dataSourceId: "data-source-id",
+})
+```
+
+`createClientFromEnvironment(env)` is available when a function needs to supply a specific environment object, such as in tests.
+
+## Initialization
+
+Entity operations use the app identity from the token and `X-App-Id`, so they are available immediately. Custom queries require a data source ID.
+
+If `MITRA_DATA_SOURCE_ID` or `dataSourceId` is not configured, call `init()` once before executing queries. It resolves the data source from Code Studio and is safe to call concurrently.
+
+```typescript
+const mitra = createClient()
+await mitra.init()
+
+const result = await mitra.queries.execute("5df41c69-2a74-4db6-9cca-4af2b473941f", {
+  status: "active",
+})
+```
+
+## API
+
+### Current user
+
+```typescript
+const user = await mitra.auth.me()
+```
+
+The SDK only reads the current authenticated user. Login, logout, browser storage, and token refresh belong to the Platform SDK used by frontend applications.
+
+### Entities
+
+```typescript
+type Task = {
+  id: string
+  title: string
+  status: "pending" | "done"
+}
+
+const tasks = mitra.entities.getTable<Task>("Task")
+const recent = await tasks.list({ sort: "-created_at", limit: 20 })
+const pending = await tasks.filter({ status: "pending" })
+const created = await tasks.create({ title: "Review order" })
+await tasks.update(created.id, { status: "done" })
+await tasks.delete(created.id)
+
+const dynamic = await mitra.entities.Task.list()
+```
+
+Available methods are `list`, `filter`, `get`, `create`, `bulkCreate`, `update`, `delete`, and `deleteMany`.
+
+### Custom queries
+
+```typescript
+await mitra.init()
+const result = await mitra.queries.execute("5df41c69-2a74-4db6-9cca-4af2b473941f", {
+  customerId: "customer-id",
+})
+```
+
+### Server Functions
+
+`execute` waits for a terminal execution response. `executeAsync` requests asynchronous execution and returns the pending execution record.
+
+```typescript
+const completed = await mitra.functions.execute("function-id", { orderId: "order-id" })
+const pending = await mitra.functions.executeAsync("function-id", { orderId: "order-id" })
+const current = await mitra.functions.getExecution(pending.id)
+await mitra.functions.cancelExecution(pending.id)
+```
+
+### Integrations
+
+```typescript
+const resource = await mitra.integration.executeResource("resource-id", {
+  description: "Notebook",
+})
+
+const proxy = await mitra.integration.execute("config-id", {
+  method: "GET",
+  endpoint: "/users",
+  queryParams: { limit: "10" },
+})
+```
+
+Credentials configured for an integration are injected by the Integration service. Do not pass provider credentials through function input.
+
+## Errors and request behavior
+
+API, timeout, invalid response, and network failures throw `MitraApiError`. The error exposes `status`, `code`, `details`, `requestId`, and `retryable`, preserving API metadata when it is provided. Configuration failures throw `MitraConfigurationError`.
+
+When an API error omits `retryable`, the HTTP adapter classifies 4xx responses
+as `false` and 5xx responses as `true`. This field is diagnostic classification
+only. The SDK still makes one attempt and never retries a request automatically.
+
+The Python package uses idiomatic specialized names for local failures. JavaScript `REQUEST_TIMEOUT` and `NETWORK_ERROR` map to Python `MitraNetworkError`, while JavaScript `INVALID_RESPONSE` maps to Python `MitraResponseError`. API responses use `MitraApiError` in both packages.
+
+Every request sends `Authorization: Bearer <token>` and `X-App-Id`. The default timeout is 10 seconds. Requests are never retried automatically, which avoids replaying writes with unknown idempotency.
+
+The access token is redacted from API error messages and error details.
+
+## Contract parity
+
+The test suite reads SDK-PARITY-001 directly from the installed
+`@mitralab.io/sdk-core` package. The source manifest pins Core version 0.1.0,
+the SHA-256 digest, and the full source commit
+`b513454d0d1f7344a4656cd9c0e1e32530c5ea90`. It does not duplicate the corpus.
+
+The JavaScript consumer requirement is exactly `httpAdapterCases: all`. Tests
+execute all recorded 404, 503, and timeout cases through the public client and
+the real `HttpClient`, using a mock fetch only at the network boundary. They
+verify the request and the complete error semantics. Continuous integration and
+release gates also download the canonical file from the public Core repository
+at the pinned commit and compare it byte for byte with the installed package.
+
+## Scope
+
+Version 0.1 includes application runtime operations: current user, entity CRUD, custom query execution, Server Function execution management, and integrations. Administrative control-plane methods and the legacy messenger API are intentionally excluded.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+`@mitralab.io/sdk-core@0.1.0` is resolved from the public npm registry and
+locked by integrity in `package-lock.json`. Do not replace it with a `file:`
+dependency or a local tarball.
+
+The contract source can be checked explicitly without changing the manifest or
+lockfile:
+
+```bash
+npm run check:contracts -- --canonical /path/to/sdk-parity.json
+```
+
+The package builds ESM, CommonJS, and TypeScript declarations in `dist/`. Tests enforce at least 80 percent coverage for lines, functions, branches, and statements.

package/contracts/sdk-core-v0.1.0.manifest.json

@@ -0,0 +1,15 @@
+{
+  "contract": "SDK-PARITY-001",
+  "version": "0.1.0",
+  "dependency": {
+    "package": "@mitralab.io/sdk-core",
+    "version": "0.1.0",
+    "contractPath": "contracts/v0.1.0/sdk-parity.json"
+  },
+  "source": {
+    "repository": "https://github.com/mitralab-dev/mitra-core-sdk",
+    "commit": "b513454d0d1f7344a4656cd9c0e1e32530c5ea90",
+    "path": "contracts/v0.1.0/sdk-parity.json"
+  },
+  "sha256": "600be3688cea7cfef16a8cf347516e87949b8e4151efb2c4136a2345557dde70"
+}

package/dist/index.cjs

@@ -0,0 +1,328 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MitraApiError: () => MitraApiError,
+  MitraConfigurationError: () => MitraConfigurationError,
+  createClient: () => createClient,
+  createClientFromEnvironment: () => createClientFromEnvironment
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_sdk_core = require("@mitralab.io/sdk-core");
+
+// src/errors.ts
+var MitraConfigurationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MitraConfigurationError";
+  }
+};
+var MitraApiError = class extends Error {
+  status;
+  code;
+  details;
+  requestId;
+  retryable;
+  constructor(message, status, options = {}) {
+    super(message);
+    this.name = "MitraApiError";
+    this.status = status;
+    this.code = options.code;
+    this.details = options.details;
+    this.requestId = options.requestId;
+    this.retryable = options.retryable;
+  }
+};
+
+// src/config.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+function readDefaultEnvironment() {
+  return typeof process === "undefined" ? {} : process.env;
+}
+function requiredValue(value, name) {
+  if (!value?.trim()) {
+    throw new MitraConfigurationError(`${name} is required`);
+  }
+  return value.trim();
+}
+function normalizeApiUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new MitraConfigurationError("apiUrl must be a valid HTTP or HTTPS URL");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new MitraConfigurationError("apiUrl must be a valid HTTP or HTTPS URL");
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash || value.includes("?") || value.includes("#")) {
+    throw new MitraConfigurationError(
+      "apiUrl must not include credentials, query parameters, or a fragment"
+    );
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+function resolveConfig(config = {}, environment = readDefaultEnvironment()) {
+  const apiUrl = normalizeApiUrl(
+    requiredValue(config.apiUrl ?? environment.MITRA_API_URL, "apiUrl")
+  );
+  const accessToken = requiredValue(
+    config.accessToken ?? environment.MITRA_PLATFORM_ACCESS_TOKEN,
+    "accessToken"
+  );
+  const appId = requiredValue(config.appId ?? environment.MITRA_APP_ID, "appId");
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchImplementation = config.fetch ?? globalThis.fetch;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new MitraConfigurationError("timeoutMs must be a positive number");
+  }
+  if (typeof fetchImplementation !== "function") {
+    throw new MitraConfigurationError("A fetch implementation is required");
+  }
+  const dataSourceId = config.dataSourceId ?? environment.MITRA_DATA_SOURCE_ID;
+  if (dataSourceId !== void 0 && !dataSourceId.trim()) {
+    throw new MitraConfigurationError("dataSourceId must not be empty when provided");
+  }
+  return {
+    apiUrl,
+    accessToken,
+    appId,
+    ...dataSourceId === void 0 ? {} : { dataSourceId: dataSourceId.trim() },
+    timeoutMs,
+    fetch: fetchImplementation
+  };
+}
+
+// src/http-client.ts
+var bearerCredentialPattern = /(\bBearer\s+)\S+/gi;
+function redactText(value, accessToken) {
+  return value.replace(bearerCredentialPattern, "$1[REDACTED]").split(accessToken).join("[REDACTED]");
+}
+function redactDetails(value, accessToken) {
+  if (typeof value === "string") return redactText(value, accessToken);
+  if (Array.isArray(value)) return value.map((item) => redactDetails(item, accessToken));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => {
+        const sensitive = /token|authorization|password|secret|api.?key/i.test(key);
+        return [
+          redactText(key, accessToken),
+          sensitive ? "[REDACTED]" : redactDetails(entry, accessToken)
+        ];
+      })
+    );
+  }
+  return value;
+}
+function optionalString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+var HttpClient = class {
+  #accessToken;
+  baseUrl;
+  appId;
+  timeoutMs;
+  fetchImplementation;
+  constructor(config) {
+    this.baseUrl = config.baseUrl;
+    this.#accessToken = config.accessToken;
+    this.appId = config.appId;
+    this.timeoutMs = config.timeoutMs;
+    this.fetchImplementation = config.fetch;
+  }
+  async request(path, options = {}) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(options.params ?? {})) {
+      if (value !== void 0) url.searchParams.append(key, String(value));
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    const hasBody = options.body !== void 0;
+    try {
+      const response = await this.fetchImplementation(url, {
+        method: options.method ?? "GET",
+        headers: {
+          Accept: "application/json",
+          ...hasBody ? { "Content-Type": "application/json" } : {},
+          Authorization: `Bearer ${this.#accessToken}`,
+          "X-App-Id": this.appId,
+          ...options.headers
+        },
+        ...hasBody ? { body: JSON.stringify(options.body) } : {},
+        redirect: "manual",
+        signal: controller.signal
+      });
+      if (response.status === 204) return void 0;
+      const text = await response.text();
+      let payload;
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        if (response.ok) {
+          throw new MitraApiError("The Mitra API returned invalid JSON", response.status, {
+            code: "INVALID_RESPONSE",
+            retryable: false
+          });
+        }
+        payload = {};
+      }
+      if (!response.ok) {
+        const errorPayload = payload && typeof payload === "object" ? payload : {};
+        const rawMessage = optionalString(errorPayload.message);
+        const message = redactText(
+          rawMessage ?? `Request failed with status ${response.status}`,
+          this.#accessToken
+        );
+        const rawRequestId = optionalString(errorPayload.request_id) ?? optionalString(errorPayload.requestId) ?? response.headers.get("X-Request-Id") ?? void 0;
+        const rawCode = optionalString(errorPayload.error_code) ?? optionalString(errorPayload.code);
+        const requestId = rawRequestId === void 0 ? void 0 : redactText(rawRequestId, this.#accessToken);
+        const code = rawCode === void 0 ? void 0 : redactText(rawCode, this.#accessToken);
+        const retryable = typeof errorPayload.retryable === "boolean" ? errorPayload.retryable : response.status >= 500;
+        throw new MitraApiError(message, response.status, {
+          ...code === void 0 ? {} : { code },
+          ...errorPayload.details === void 0 ? {} : { details: redactDetails(errorPayload.details, this.#accessToken) },
+          ...requestId === void 0 ? {} : { requestId },
+          ...retryable === void 0 ? {} : { retryable }
+        });
+      }
+      return payload;
+    } catch (error) {
+      if (error instanceof MitraApiError) throw error;
+      if (controller.signal.aborted) {
+        throw new MitraApiError("Mitra request timed out", 0, {
+          code: "REQUEST_TIMEOUT",
+          retryable: true
+        });
+      }
+      throw new MitraApiError("The Mitra API request failed", 0, {
+        code: "NETWORK_ERROR",
+        retryable: true
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  get(path, params) {
+    return this.request(path, { method: "GET", ...params === void 0 ? {} : { params } });
+  }
+  post(path, body, headers) {
+    return this.request(path, {
+      method: "POST",
+      ...body === void 0 ? {} : { body },
+      ...headers === void 0 ? {} : { headers }
+    });
+  }
+  put(path, body) {
+    return this.request(path, { method: "PUT", body });
+  }
+  delete(path, params) {
+    return this.request(path, {
+      method: "DELETE",
+      ...params === void 0 ? {} : { params }
+    });
+  }
+};
+
+// src/client.ts
+var coreErrors = {
+  configuration: (message) => new MitraConfigurationError(message),
+  invalidResponse: (message) => new MitraApiError(message, 200, { code: "INVALID_RESPONSE", retryable: false })
+};
+var DefaultMitraClient = class {
+  auth;
+  entities;
+  functions;
+  integration;
+  queries;
+  #dataSourceId;
+  #initPromise;
+  #appId;
+  #codeStudioHttpClient;
+  constructor(config) {
+    this.#appId = config.appId;
+    this.#dataSourceId = config.dataSourceId;
+    const httpClient = (service) => new HttpClient({
+      baseUrl: `${config.apiUrl}/${service}`,
+      accessToken: config.accessToken,
+      appId: config.appId,
+      timeoutMs: config.timeoutMs,
+      fetch: config.fetch
+    });
+    const core = (0, import_sdk_core.createSdkCore)({
+      transports: {
+        auth: httpClient("iam"),
+        dataManager: httpClient("data-manager"),
+        functions: httpClient("functions"),
+        integration: httpClient("integration")
+      },
+      getDataSourceId: () => this.#dataSourceId,
+      functions: { executeInvocationType: "sync", emptyInput: "empty-object" },
+      errors: coreErrors
+    });
+    this.auth = core.auth;
+    this.entities = core.entities;
+    this.functions = core.functions;
+    this.integration = core.integration;
+    this.queries = core.queries;
+    this.#codeStudioHttpClient = httpClient("code-studio");
+  }
+  init() {
+    if (this.#dataSourceId) return Promise.resolve();
+    if (!this.#initPromise) {
+      this.#initPromise = this.resolveDataSourceId().catch((error) => {
+        this.#initPromise = void 0;
+        throw error;
+      });
+    }
+    return this.#initPromise;
+  }
+  async resolveDataSourceId() {
+    const appInfo = (0, import_sdk_core.expectObject)(
+      await this.#codeStudioHttpClient.get(
+        `/api/v1/apps/${(0, import_sdk_core.encodePathSegment)(this.#appId, "appId", coreErrors)}/info`
+      ),
+      "App info response",
+      coreErrors
+    );
+    if (!appInfo.dataSourceId?.trim()) {
+      throw new MitraApiError("The app info response does not include a dataSourceId", 200, {
+        code: "INVALID_RESPONSE",
+        retryable: false
+      });
+    }
+    this.#dataSourceId = appInfo.dataSourceId;
+  }
+};
+function createClient(config = {}) {
+  return new DefaultMitraClient(resolveConfig(config));
+}
+function createClientFromEnvironment(environment) {
+  return new DefaultMitraClient(resolveConfig({}, environment));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MitraApiError,
+  MitraConfigurationError,
+  createClient,
+  createClientFromEnvironment
+});

package/dist/index.d.cts

@@ -0,0 +1,50 @@
+import { AuthModule, EntitiesProxy, FunctionsModule, IntegrationModule, QueriesModule } from '@mitralab.io/sdk-core';
+export { EntityListOptions, EntityTable, FunctionExecution, Plan, ProxyInput, ProxyResult, QueryResult, Tenant, User } from '@mitralab.io/sdk-core';
+
+type Fetch = typeof globalThis.fetch;
+interface MitraEnvironment {
+    MITRA_API_URL?: string;
+    MITRA_PLATFORM_ACCESS_TOKEN?: string;
+    MITRA_APP_ID?: string;
+    MITRA_DATA_SOURCE_ID?: string;
+    [key: string]: string | undefined;
+}
+interface MitraClientConfig {
+    apiUrl?: string;
+    accessToken?: string;
+    appId?: string;
+    dataSourceId?: string;
+    timeoutMs?: number;
+    fetch?: Fetch;
+}
+
+interface MitraClient {
+    init(): Promise<void>;
+    readonly auth: AuthModule;
+    readonly entities: EntitiesProxy;
+    readonly functions: FunctionsModule;
+    readonly integration: IntegrationModule;
+    readonly queries: QueriesModule;
+}
+declare function createClient(config?: MitraClientConfig): MitraClient;
+declare function createClientFromEnvironment(environment?: MitraEnvironment): MitraClient;
+
+declare class MitraConfigurationError extends Error {
+    constructor(message: string);
+}
+interface MitraApiErrorOptions {
+    code?: string;
+    details?: unknown;
+    requestId?: string;
+    retryable?: boolean;
+}
+declare class MitraApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly details: unknown;
+    readonly requestId: string | undefined;
+    readonly retryable: boolean | undefined;
+    constructor(message: string, status: number, options?: MitraApiErrorOptions);
+}
+
+export { type Fetch, MitraApiError, type MitraClient, type MitraClientConfig, MitraConfigurationError, type MitraEnvironment, createClient, createClientFromEnvironment };

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import { AuthModule, EntitiesProxy, FunctionsModule, IntegrationModule, QueriesModule } from '@mitralab.io/sdk-core';
+export { EntityListOptions, EntityTable, FunctionExecution, Plan, ProxyInput, ProxyResult, QueryResult, Tenant, User } from '@mitralab.io/sdk-core';
+
+type Fetch = typeof globalThis.fetch;
+interface MitraEnvironment {
+    MITRA_API_URL?: string;
+    MITRA_PLATFORM_ACCESS_TOKEN?: string;
+    MITRA_APP_ID?: string;
+    MITRA_DATA_SOURCE_ID?: string;
+    [key: string]: string | undefined;
+}
+interface MitraClientConfig {
+    apiUrl?: string;
+    accessToken?: string;
+    appId?: string;
+    dataSourceId?: string;
+    timeoutMs?: number;
+    fetch?: Fetch;
+}
+
+interface MitraClient {
+    init(): Promise<void>;
+    readonly auth: AuthModule;
+    readonly entities: EntitiesProxy;
+    readonly functions: FunctionsModule;
+    readonly integration: IntegrationModule;
+    readonly queries: QueriesModule;
+}
+declare function createClient(config?: MitraClientConfig): MitraClient;
+declare function createClientFromEnvironment(environment?: MitraEnvironment): MitraClient;
+
+declare class MitraConfigurationError extends Error {
+    constructor(message: string);
+}
+interface MitraApiErrorOptions {
+    code?: string;
+    details?: unknown;
+    requestId?: string;
+    retryable?: boolean;
+}
+declare class MitraApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly details: unknown;
+    readonly requestId: string | undefined;
+    readonly retryable: boolean | undefined;
+    constructor(message: string, status: number, options?: MitraApiErrorOptions);
+}
+
+export { type Fetch, MitraApiError, type MitraClient, type MitraClientConfig, MitraConfigurationError, type MitraEnvironment, createClient, createClientFromEnvironment };

package/dist/index.js

@@ -0,0 +1,302 @@
+// src/client.ts
+import {
+  createSdkCore,
+  encodePathSegment,
+  expectObject
+} from "@mitralab.io/sdk-core";
+
+// src/errors.ts
+var MitraConfigurationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MitraConfigurationError";
+  }
+};
+var MitraApiError = class extends Error {
+  status;
+  code;
+  details;
+  requestId;
+  retryable;
+  constructor(message, status, options = {}) {
+    super(message);
+    this.name = "MitraApiError";
+    this.status = status;
+    this.code = options.code;
+    this.details = options.details;
+    this.requestId = options.requestId;
+    this.retryable = options.retryable;
+  }
+};
+
+// src/config.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+function readDefaultEnvironment() {
+  return typeof process === "undefined" ? {} : process.env;
+}
+function requiredValue(value, name) {
+  if (!value?.trim()) {
+    throw new MitraConfigurationError(`${name} is required`);
+  }
+  return value.trim();
+}
+function normalizeApiUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new MitraConfigurationError("apiUrl must be a valid HTTP or HTTPS URL");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new MitraConfigurationError("apiUrl must be a valid HTTP or HTTPS URL");
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash || value.includes("?") || value.includes("#")) {
+    throw new MitraConfigurationError(
+      "apiUrl must not include credentials, query parameters, or a fragment"
+    );
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+function resolveConfig(config = {}, environment = readDefaultEnvironment()) {
+  const apiUrl = normalizeApiUrl(
+    requiredValue(config.apiUrl ?? environment.MITRA_API_URL, "apiUrl")
+  );
+  const accessToken = requiredValue(
+    config.accessToken ?? environment.MITRA_PLATFORM_ACCESS_TOKEN,
+    "accessToken"
+  );
+  const appId = requiredValue(config.appId ?? environment.MITRA_APP_ID, "appId");
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchImplementation = config.fetch ?? globalThis.fetch;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new MitraConfigurationError("timeoutMs must be a positive number");
+  }
+  if (typeof fetchImplementation !== "function") {
+    throw new MitraConfigurationError("A fetch implementation is required");
+  }
+  const dataSourceId = config.dataSourceId ?? environment.MITRA_DATA_SOURCE_ID;
+  if (dataSourceId !== void 0 && !dataSourceId.trim()) {
+    throw new MitraConfigurationError("dataSourceId must not be empty when provided");
+  }
+  return {
+    apiUrl,
+    accessToken,
+    appId,
+    ...dataSourceId === void 0 ? {} : { dataSourceId: dataSourceId.trim() },
+    timeoutMs,
+    fetch: fetchImplementation
+  };
+}
+
+// src/http-client.ts
+var bearerCredentialPattern = /(\bBearer\s+)\S+/gi;
+function redactText(value, accessToken) {
+  return value.replace(bearerCredentialPattern, "$1[REDACTED]").split(accessToken).join("[REDACTED]");
+}
+function redactDetails(value, accessToken) {
+  if (typeof value === "string") return redactText(value, accessToken);
+  if (Array.isArray(value)) return value.map((item) => redactDetails(item, accessToken));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => {
+        const sensitive = /token|authorization|password|secret|api.?key/i.test(key);
+        return [
+          redactText(key, accessToken),
+          sensitive ? "[REDACTED]" : redactDetails(entry, accessToken)
+        ];
+      })
+    );
+  }
+  return value;
+}
+function optionalString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+var HttpClient = class {
+  #accessToken;
+  baseUrl;
+  appId;
+  timeoutMs;
+  fetchImplementation;
+  constructor(config) {
+    this.baseUrl = config.baseUrl;
+    this.#accessToken = config.accessToken;
+    this.appId = config.appId;
+    this.timeoutMs = config.timeoutMs;
+    this.fetchImplementation = config.fetch;
+  }
+  async request(path, options = {}) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(options.params ?? {})) {
+      if (value !== void 0) url.searchParams.append(key, String(value));
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    const hasBody = options.body !== void 0;
+    try {
+      const response = await this.fetchImplementation(url, {
+        method: options.method ?? "GET",
+        headers: {
+          Accept: "application/json",
+          ...hasBody ? { "Content-Type": "application/json" } : {},
+          Authorization: `Bearer ${this.#accessToken}`,
+          "X-App-Id": this.appId,
+          ...options.headers
+        },
+        ...hasBody ? { body: JSON.stringify(options.body) } : {},
+        redirect: "manual",
+        signal: controller.signal
+      });
+      if (response.status === 204) return void 0;
+      const text = await response.text();
+      let payload;
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        if (response.ok) {
+          throw new MitraApiError("The Mitra API returned invalid JSON", response.status, {
+            code: "INVALID_RESPONSE",
+            retryable: false
+          });
+        }
+        payload = {};
+      }
+      if (!response.ok) {
+        const errorPayload = payload && typeof payload === "object" ? payload : {};
+        const rawMessage = optionalString(errorPayload.message);
+        const message = redactText(
+          rawMessage ?? `Request failed with status ${response.status}`,
+          this.#accessToken
+        );
+        const rawRequestId = optionalString(errorPayload.request_id) ?? optionalString(errorPayload.requestId) ?? response.headers.get("X-Request-Id") ?? void 0;
+        const rawCode = optionalString(errorPayload.error_code) ?? optionalString(errorPayload.code);
+        const requestId = rawRequestId === void 0 ? void 0 : redactText(rawRequestId, this.#accessToken);
+        const code = rawCode === void 0 ? void 0 : redactText(rawCode, this.#accessToken);
+        const retryable = typeof errorPayload.retryable === "boolean" ? errorPayload.retryable : response.status >= 500;
+        throw new MitraApiError(message, response.status, {
+          ...code === void 0 ? {} : { code },
+          ...errorPayload.details === void 0 ? {} : { details: redactDetails(errorPayload.details, this.#accessToken) },
+          ...requestId === void 0 ? {} : { requestId },
+          ...retryable === void 0 ? {} : { retryable }
+        });
+      }
+      return payload;
+    } catch (error) {
+      if (error instanceof MitraApiError) throw error;
+      if (controller.signal.aborted) {
+        throw new MitraApiError("Mitra request timed out", 0, {
+          code: "REQUEST_TIMEOUT",
+          retryable: true
+        });
+      }
+      throw new MitraApiError("The Mitra API request failed", 0, {
+        code: "NETWORK_ERROR",
+        retryable: true
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  get(path, params) {
+    return this.request(path, { method: "GET", ...params === void 0 ? {} : { params } });
+  }
+  post(path, body, headers) {
+    return this.request(path, {
+      method: "POST",
+      ...body === void 0 ? {} : { body },
+      ...headers === void 0 ? {} : { headers }
+    });
+  }
+  put(path, body) {
+    return this.request(path, { method: "PUT", body });
+  }
+  delete(path, params) {
+    return this.request(path, {
+      method: "DELETE",
+      ...params === void 0 ? {} : { params }
+    });
+  }
+};
+
+// src/client.ts
+var coreErrors = {
+  configuration: (message) => new MitraConfigurationError(message),
+  invalidResponse: (message) => new MitraApiError(message, 200, { code: "INVALID_RESPONSE", retryable: false })
+};
+var DefaultMitraClient = class {
+  auth;
+  entities;
+  functions;
+  integration;
+  queries;
+  #dataSourceId;
+  #initPromise;
+  #appId;
+  #codeStudioHttpClient;
+  constructor(config) {
+    this.#appId = config.appId;
+    this.#dataSourceId = config.dataSourceId;
+    const httpClient = (service) => new HttpClient({
+      baseUrl: `${config.apiUrl}/${service}`,
+      accessToken: config.accessToken,
+      appId: config.appId,
+      timeoutMs: config.timeoutMs,
+      fetch: config.fetch
+    });
+    const core = createSdkCore({
+      transports: {
+        auth: httpClient("iam"),
+        dataManager: httpClient("data-manager"),
+        functions: httpClient("functions"),
+        integration: httpClient("integration")
+      },
+      getDataSourceId: () => this.#dataSourceId,
+      functions: { executeInvocationType: "sync", emptyInput: "empty-object" },
+      errors: coreErrors
+    });
+    this.auth = core.auth;
+    this.entities = core.entities;
+    this.functions = core.functions;
+    this.integration = core.integration;
+    this.queries = core.queries;
+    this.#codeStudioHttpClient = httpClient("code-studio");
+  }
+  init() {
+    if (this.#dataSourceId) return Promise.resolve();
+    if (!this.#initPromise) {
+      this.#initPromise = this.resolveDataSourceId().catch((error) => {
+        this.#initPromise = void 0;
+        throw error;
+      });
+    }
+    return this.#initPromise;
+  }
+  async resolveDataSourceId() {
+    const appInfo = expectObject(
+      await this.#codeStudioHttpClient.get(
+        `/api/v1/apps/${encodePathSegment(this.#appId, "appId", coreErrors)}/info`
+      ),
+      "App info response",
+      coreErrors
+    );
+    if (!appInfo.dataSourceId?.trim()) {
+      throw new MitraApiError("The app info response does not include a dataSourceId", 200, {
+        code: "INVALID_RESPONSE",
+        retryable: false
+      });
+    }
+    this.#dataSourceId = appInfo.dataSourceId;
+  }
+};
+function createClient(config = {}) {
+  return new DefaultMitraClient(resolveConfig(config));
+}
+function createClientFromEnvironment(environment) {
+  return new DefaultMitraClient(resolveConfig({}, environment));
+}
+export {
+  MitraApiError,
+  MitraConfigurationError,
+  createClient,
+  createClientFromEnvironment
+};

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@mitralab.io/functions-sdk",
+  "version": "0.1.0",
+  "description": "JavaScript and TypeScript SDK for Mitra Server Functions",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "contracts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "check:exports": "node scripts/check-exports.mjs",
+    "check:contracts": "node scripts/check-contract-corpus.mjs",
+    "pack:check": "npm pack --dry-run",
+    "smoke:package": "node scripts/smoke-package.mjs",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build && npm run check:exports && npm run check:contracts && npm run pack:check && npm run smoke:package",
+    "prepublishOnly": "npm run check"
+  },
+  "keywords": [
+    "mitra",
+    "sdk",
+    "serverless",
+    "functions"
+  ],
+  "author": "Mitra Platform",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mitralab-dev/mitra-functions-sdk-js"
+  },
+  "homepage": "https://github.com/mitralab-dev/mitra-functions-sdk-js#readme",
+  "bugs": {
+    "url": "https://github.com/mitralab-dev/mitra-functions-sdk-js/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@mitralab.io/sdk-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.39.1",
+    "globals": "^16.5.0",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "~8.55.0",
+    "vite": "~6.4.3",
+    "vitest": "^3.2.4"
+  },
+  "overrides": {
+    "esbuild": "^0.25.0",
+    "test-exclude": "7.0.1"
+  }
+}