@trackunit/serverside-utils 0.0.2

package/README.md

@@ -0,0 +1,20 @@
+# Trackunit serverside-utils
+
+The `@trackunit/serverside-utils` package provides utilities for building serverside extensions in the Iris App SDK.
+
+This library is exposed publicly for use in the Trackunit [Iris App SDK](https://www.npmjs.com/package/@trackunit/iris-app).
+
+For more info and a full guide on Iris App SDK Development, please visit our [Developer Hub](https://developers.trackunit.com/).
+
+## Installation
+
+```bash
+yarn add @trackunit/serverside-utils
+```
+
+## Trackunit
+
+This package was developed by Trackunit ApS.
+Trackunit is the leading SaaS-based IoT solution for the construction industry, offering an ecosystem of hardware, fleet management software & telematics.
+
+![The Trackunit logo](https://trackunit.com/wp-content/uploads/2022/03/top-logo.svg)

package/index.cjs.js

@@ -0,0 +1,251 @@
+'use strict';
+
+var jwtDecode = require('jwt-decode');
+var zod = require('zod');
+
+/**
+ * Header key for the account admin iris app token.
+ * Used by the SDK server to pass admin tokens to serverside functions.
+ *
+ * Uses vendor prefix "tu-" (Trackunit) per RFC 6648 which deprecated the "X-" convention.
+ */
+const ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER = "tu-account-admin-iris-app-token";
+/**
+ * Header key for the forwarded authorization token.
+ * The original user authorization token is moved to this header.
+ *
+ * Uses vendor prefix "tu-" (Trackunit) per RFC 6648 which deprecated the "X-" convention.
+ */
+const FORWARDED_AUTHORIZATION_HEADER = "tu-forwarded-authorization";
+
+/**
+ * Removes the "Bearer " prefix from a token string if present.
+ *
+ * @param token - The token string, possibly prefixed with "Bearer "
+ * @returns {string} The token without the "Bearer " prefix
+ */
+const stripBearerPrefix = (token) => {
+    return token.replace(/^(?:Bearer\s+)+/i, "").trim();
+};
+
+/**
+ * Retrieves the user token from the request headers.
+ *
+ * @param options - The options object
+ * @param options.context - Hono request context
+ * @returns {string | undefined} The user token (without "Bearer " prefix), or undefined if not found
+ * @example
+ * ```typescript
+ * import { getUserToken } from "@trackunit/serverside-utils";
+ *
+ * app.get("/data", async (c) => {
+ *   const token = getUserToken({ context: c });
+ *   if (!token) {
+ *     return c.json({ error: "Unauthorized" }, 401);
+ *   }
+ *   // Use token for API calls...
+ * });
+ * ```
+ */
+const getUserToken = ({ context }) => {
+    const forwardedAuth = context.req.header(FORWARDED_AUTHORIZATION_HEADER);
+    if (forwardedAuth) {
+        return stripBearerPrefix(forwardedAuth);
+    }
+    // Fall back to standard Authorization header
+    const authorization = context.req.header("authorization");
+    if (authorization) {
+        return stripBearerPrefix(authorization);
+    }
+    return undefined;
+};
+
+const JwtAccountPayloadSchema = zod.z.object({
+    accountId: zod.z.string().optional(),
+    assumedAccountId: zod.z.string().optional(),
+});
+/**
+ * Extracts the account ID from the user token in the request.
+ *
+ * Trackunit tokens may contain both `accountId` (token owner) and `assumedAccountId`
+ * (account being acted upon). This function returns the effective account ID,
+ * preferring `assumedAccountId` when present.
+ *
+ * @param options - The options object
+ * @param options.context - Hono request context
+ * @returns {AccountIdResult} The effective account ID and the raw assumedAccountId (if present)
+ * @throws Error if no user token is found or the token has no account ID
+ * @example
+ * ```typescript
+ * // Simple usage — just get the effective account ID:
+ * const { accountId } = getAccountId({ context: c });
+ *
+ * // When you need to know if the user is assuming an account:
+ * const { accountId, assumedAccountId } = getAccountId({ context: c });
+ * ```
+ */
+const getAccountId = ({ context }) => {
+    const userToken = getUserToken({ context });
+    if (!userToken) {
+        throw new Error("Missing user token");
+    }
+    try {
+        const tokenWithoutBearer = stripBearerPrefix(userToken);
+        const payload = jwtDecode(tokenWithoutBearer);
+        const parseResult = JwtAccountPayloadSchema.safeParse(payload);
+        if (!parseResult.success) {
+            throw new Error("JWT payload missing accountId");
+        }
+        const { accountId, assumedAccountId } = parseResult.data;
+        const effectiveAccountId = assumedAccountId ?? accountId;
+        if (!effectiveAccountId) {
+            throw new Error("JWT payload missing accountId");
+        }
+        return {
+            accountId: effectiveAccountId,
+            assumedAccountId,
+            tokenAccountId: accountId,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "JWT payload missing accountId") {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : "Unknown error";
+        throw new Error(`Failed to extract accountId from user token: ${message}`);
+    }
+};
+
+const SecretsResponseSchema = zod.z.object({
+    secrets: zod.z.record(zod.z.string(), zod.z.string()),
+});
+/**
+ * Fetches a secret from the SDK Server.
+ *
+ * By default fetches **app-level** secrets (`GET /secrets`).
+ * Pass `accountScoped: true` to fetch **account-scoped** secrets (`GET /secrets/:accountId`).
+ *
+ * For local development, set the secret as an environment variable with the same name
+ * as the secretKey (e.g., `API_KEY=xxx` in your `.env` file).
+ *
+ * @param options - The options object
+ * @param options.context - Hono request context
+ * @param options.secretKey - Key name of the secret
+ * @param options.accountScoped - When true, fetches account-scoped secrets (requires user token with accountId)
+ * @returns {Promise<string>} The secret value
+ * @throws Error if required headers or env vars are missing, or secret not found
+ * @example
+ * ```typescript
+ * // App-level secret (default)
+ * const apiKey = await getSecret({ context: c, secretKey: "API_KEY" });
+ *
+ * // Account-scoped secret
+ * const accountKey = await getSecret({ context: c, secretKey: "API_KEY", accountScoped: true });
+ * ```
+ */
+const getSecret = async ({ context, secretKey, accountScoped = false, }) => {
+    // Local development: use env var with same name as secretKey
+    try {
+        const envValue = process.env[secretKey];
+        if (envValue) {
+            return envValue;
+        }
+    }
+    catch {
+        // Ignore error when getting secret from environment variable. Deno blocks access to process.env in serverside functions.
+    }
+    const adminToken = context.req.header(ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER);
+    if (!adminToken) {
+        throw new Error(`Missing required header: ${ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER}`);
+    }
+    const sdkServerUrl = process.env.SDK_SERVER_URL;
+    if (!sdkServerUrl) {
+        throw new Error("Missing required environment variable: SDK_SERVER_URL");
+    }
+    const secretsPath = accountScoped ? `/secrets/${getAccountId({ context }).accountId}` : "/secrets";
+    const secretsUrl = new URL(secretsPath, sdkServerUrl).href;
+    const res = await fetch(secretsUrl, {
+        headers: { Authorization: adminToken },
+    });
+    if (!res.ok) {
+        let errorBody = "";
+        try {
+            const text = await res.text();
+            errorBody = text.length > 200 ? `${text.slice(0, 200)}...` : text;
+        }
+        catch {
+            // Ignore body read errors
+        }
+        throw new Error(`Failed to fetch secret "${secretKey}" from ${secretsUrl}: ${res.status} ${res.statusText}${errorBody ? ` - ${errorBody}` : ""}`);
+    }
+    const responseData = await res.json();
+    const parseResult = SecretsResponseSchema.safeParse(responseData);
+    if (!parseResult.success) {
+        throw new Error(`Invalid secrets response from ${secretsUrl}: ${parseResult.error.message}`);
+    }
+    const secret = parseResult.data.secrets[secretKey];
+    if (!secret) {
+        throw new Error(`Secret "${secretKey}" not found in response from ${secretsUrl}. Available keys: ${Object.keys(parseResult.data.secrets).join(", ") || "(none)"}`);
+    }
+    return secret;
+};
+
+const DatabricksTokenResponseSchema = zod.z.object({
+    access_token: zod.z.string(),
+    expires_in: zod.z.number().optional(),
+});
+const buildDatabricksUrl = (host, path) => {
+    const trimmed = host.trim();
+    const base = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+    return new URL(path, base).toString();
+};
+/**
+ * Obtains a Databricks OAuth access token using the client credentials flow.
+ *
+ * @example
+ *
+ * const { databricksAccessToken } = await getDatabricksAccessToken({ context: c });
+ * @param props - The properties of the request.
+ * @param props.context - The context of the request.
+ * @param props.databricksHost - The host of the Databricks instance.
+ * @param props.databricksClientId - The client ID of the Databricks application.
+ * @param props.databricksClientSecret - The client secret of the Databricks application.
+ * @param props.accountScoped - When true, fetches account-scoped secrets (requires user token with accountId)
+ * @param props.scope - The scope of the request to the Databricks token endpoint. Defaults to `all-apis`.@param options.accountScoped - When true, fetches account-scoped secrets (requires user token with accountId)
+ * @returns {Promise<{ databricksAccessToken: string; databricksTokenExpiresIn?: number }>} The access token and optional expiry in seconds.
+ */
+const getDatabricksAccessToken = async ({ context, databricksHost, databricksClientId, databricksClientSecret, accountScoped = false, scope = "all-apis", }) => {
+    const clientId = databricksClientId ?? (await getSecret({ context, secretKey: "DATABRICKS_CLIENT_ID", accountScoped }));
+    const clientSecret = databricksClientSecret ?? (await getSecret({ context, secretKey: "DATABRICKS_CLIENT_SECRET", accountScoped }));
+    const rawHost = databricksHost ?? (await getSecret({ context, secretKey: "DATABRICKS_HOST", accountScoped }));
+    const tokenUrl = buildDatabricksUrl(rawHost, "/oidc/v1/token");
+    const credentials = btoa(`${clientId}:${clientSecret}`);
+    const tokenResponse = await fetch(tokenUrl, {
+        method: "POST",
+        headers: {
+            Authorization: `Basic ${credentials}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: `grant_type=client_credentials&scope=${scope}`,
+    });
+    if (!tokenResponse.ok) {
+        const errorBody = await tokenResponse.text();
+        throw new Error(`Failed to obtain Databricks access token: ${tokenResponse.status} ${tokenResponse.statusText} - ${errorBody}`);
+    }
+    const responseData = await tokenResponse.json();
+    const parseResult = DatabricksTokenResponseSchema.safeParse(responseData);
+    if (!parseResult.success) {
+        throw new Error(`Invalid token response: ${parseResult.error.message}`);
+    }
+    return {
+        databricksAccessToken: parseResult.data.access_token,
+        databricksTokenExpiresIn: parseResult.data.expires_in,
+    };
+};
+
+exports.ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER = ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER;
+exports.FORWARDED_AUTHORIZATION_HEADER = FORWARDED_AUTHORIZATION_HEADER;
+exports.getAccountId = getAccountId;
+exports.getDatabricksAccessToken = getDatabricksAccessToken;
+exports.getSecret = getSecret;
+exports.getUserToken = getUserToken;

package/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index";

package/index.esm.js

@@ -0,0 +1,244 @@
+import jwtDecode from 'jwt-decode';
+import { z } from 'zod';
+
+/**
+ * Header key for the account admin iris app token.
+ * Used by the SDK server to pass admin tokens to serverside functions.
+ *
+ * Uses vendor prefix "tu-" (Trackunit) per RFC 6648 which deprecated the "X-" convention.
+ */
+const ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER = "tu-account-admin-iris-app-token";
+/**
+ * Header key for the forwarded authorization token.
+ * The original user authorization token is moved to this header.
+ *
+ * Uses vendor prefix "tu-" (Trackunit) per RFC 6648 which deprecated the "X-" convention.
+ */
+const FORWARDED_AUTHORIZATION_HEADER = "tu-forwarded-authorization";
+
+/**
+ * Removes the "Bearer " prefix from a token string if present.
+ *
+ * @param token - The token string, possibly prefixed with "Bearer "
+ * @returns {string} The token without the "Bearer " prefix
+ */
+const stripBearerPrefix = (token) => {
+    return token.replace(/^(?:Bearer\s+)+/i, "").trim();
+};
+
+/**
+ * Retrieves the user token from the request headers.
+ *
+ * @param options - The options object
+ * @param options.context - Hono request context
+ * @returns {string | undefined} The user token (without "Bearer " prefix), or undefined if not found
+ * @example
+ * ```typescript
+ * import { getUserToken } from "@trackunit/serverside-utils";
+ *
+ * app.get("/data", async (c) => {
+ *   const token = getUserToken({ context: c });
+ *   if (!token) {
+ *     return c.json({ error: "Unauthorized" }, 401);
+ *   }
+ *   // Use token for API calls...
+ * });
+ * ```
+ */
+const getUserToken = ({ context }) => {
+    const forwardedAuth = context.req.header(FORWARDED_AUTHORIZATION_HEADER);
+    if (forwardedAuth) {
+        return stripBearerPrefix(forwardedAuth);
+    }
+    // Fall back to standard Authorization header
+    const authorization = context.req.header("authorization");
+    if (authorization) {
+        return stripBearerPrefix(authorization);
+    }
+    return undefined;
+};
+
+const JwtAccountPayloadSchema = z.object({
+    accountId: z.string().optional(),
+    assumedAccountId: z.string().optional(),
+});
+/**
+ * Extracts the account ID from the user token in the request.
+ *
+ * Trackunit tokens may contain both `accountId` (token owner) and `assumedAccountId`
+ * (account being acted upon). This function returns the effective account ID,
+ * preferring `assumedAccountId` when present.
+ *
+ * @param options - The options object
+ * @param options.context - Hono request context
+ * @returns {AccountIdResult} The effective account ID and the raw assumedAccountId (if present)
+ * @throws Error if no user token is found or the token has no account ID
+ * @example
+ * ```typescript
+ * // Simple usage — just get the effective account ID:
+ * const { accountId } = getAccountId({ context: c });
+ *
+ * // When you need to know if the user is assuming an account:
+ * const { accountId, assumedAccountId } = getAccountId({ context: c });
+ * ```
+ */
+const getAccountId = ({ context }) => {
+    const userToken = getUserToken({ context });
+    if (!userToken) {
+        throw new Error("Missing user token");
+    }
+    try {
+        const tokenWithoutBearer = stripBearerPrefix(userToken);
+        const payload = jwtDecode(tokenWithoutBearer);
+        const parseResult = JwtAccountPayloadSchema.safeParse(payload);
+        if (!parseResult.success) {
+            throw new Error("JWT payload missing accountId");
+        }
+        const { accountId, assumedAccountId } = parseResult.data;
+        const effectiveAccountId = assumedAccountId ?? accountId;
+        if (!effectiveAccountId) {
+            throw new Error("JWT payload missing accountId");
+        }
+        return {
+            accountId: effectiveAccountId,
+            assumedAccountId,
+            tokenAccountId: accountId,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "JWT payload missing accountId") {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : "Unknown error";
+        throw new Error(`Failed to extract accountId from user token: ${message}`);
+    }
+};
+
+const SecretsResponseSchema = z.object({
+    secrets: z.record(z.string(), z.string()),
+});
+/**
+ * Fetches a secret from the SDK Server.
+ *
+ * By default fetches **app-level** secrets (`GET /secrets`).
+ * Pass `accountScoped: true` to fetch **account-scoped** secrets (`GET /secrets/:accountId`).
+ *
+ * For local development, set the secret as an environment variable with the same name
+ * as the secretKey (e.g., `API_KEY=xxx` in your `.env` file).
+ *
+ * @param options - The options object
+ * @param options.context - Hono request context
+ * @param options.secretKey - Key name of the secret
+ * @param options.accountScoped - When true, fetches account-scoped secrets (requires user token with accountId)
+ * @returns {Promise<string>} The secret value
+ * @throws Error if required headers or env vars are missing, or secret not found
+ * @example
+ * ```typescript
+ * // App-level secret (default)
+ * const apiKey = await getSecret({ context: c, secretKey: "API_KEY" });
+ *
+ * // Account-scoped secret
+ * const accountKey = await getSecret({ context: c, secretKey: "API_KEY", accountScoped: true });
+ * ```
+ */
+const getSecret = async ({ context, secretKey, accountScoped = false, }) => {
+    // Local development: use env var with same name as secretKey
+    try {
+        const envValue = process.env[secretKey];
+        if (envValue) {
+            return envValue;
+        }
+    }
+    catch {
+        // Ignore error when getting secret from environment variable. Deno blocks access to process.env in serverside functions.
+    }
+    const adminToken = context.req.header(ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER);
+    if (!adminToken) {
+        throw new Error(`Missing required header: ${ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER}`);
+    }
+    const sdkServerUrl = process.env.SDK_SERVER_URL;
+    if (!sdkServerUrl) {
+        throw new Error("Missing required environment variable: SDK_SERVER_URL");
+    }
+    const secretsPath = accountScoped ? `/secrets/${getAccountId({ context }).accountId}` : "/secrets";
+    const secretsUrl = new URL(secretsPath, sdkServerUrl).href;
+    const res = await fetch(secretsUrl, {
+        headers: { Authorization: adminToken },
+    });
+    if (!res.ok) {
+        let errorBody = "";
+        try {
+            const text = await res.text();
+            errorBody = text.length > 200 ? `${text.slice(0, 200)}...` : text;
+        }
+        catch {
+            // Ignore body read errors
+        }
+        throw new Error(`Failed to fetch secret "${secretKey}" from ${secretsUrl}: ${res.status} ${res.statusText}${errorBody ? ` - ${errorBody}` : ""}`);
+    }
+    const responseData = await res.json();
+    const parseResult = SecretsResponseSchema.safeParse(responseData);
+    if (!parseResult.success) {
+        throw new Error(`Invalid secrets response from ${secretsUrl}: ${parseResult.error.message}`);
+    }
+    const secret = parseResult.data.secrets[secretKey];
+    if (!secret) {
+        throw new Error(`Secret "${secretKey}" not found in response from ${secretsUrl}. Available keys: ${Object.keys(parseResult.data.secrets).join(", ") || "(none)"}`);
+    }
+    return secret;
+};
+
+const DatabricksTokenResponseSchema = z.object({
+    access_token: z.string(),
+    expires_in: z.number().optional(),
+});
+const buildDatabricksUrl = (host, path) => {
+    const trimmed = host.trim();
+    const base = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+    return new URL(path, base).toString();
+};
+/**
+ * Obtains a Databricks OAuth access token using the client credentials flow.
+ *
+ * @example
+ *
+ * const { databricksAccessToken } = await getDatabricksAccessToken({ context: c });
+ * @param props - The properties of the request.
+ * @param props.context - The context of the request.
+ * @param props.databricksHost - The host of the Databricks instance.
+ * @param props.databricksClientId - The client ID of the Databricks application.
+ * @param props.databricksClientSecret - The client secret of the Databricks application.
+ * @param props.accountScoped - When true, fetches account-scoped secrets (requires user token with accountId)
+ * @param props.scope - The scope of the request to the Databricks token endpoint. Defaults to `all-apis`.@param options.accountScoped - When true, fetches account-scoped secrets (requires user token with accountId)
+ * @returns {Promise<{ databricksAccessToken: string; databricksTokenExpiresIn?: number }>} The access token and optional expiry in seconds.
+ */
+const getDatabricksAccessToken = async ({ context, databricksHost, databricksClientId, databricksClientSecret, accountScoped = false, scope = "all-apis", }) => {
+    const clientId = databricksClientId ?? (await getSecret({ context, secretKey: "DATABRICKS_CLIENT_ID", accountScoped }));
+    const clientSecret = databricksClientSecret ?? (await getSecret({ context, secretKey: "DATABRICKS_CLIENT_SECRET", accountScoped }));
+    const rawHost = databricksHost ?? (await getSecret({ context, secretKey: "DATABRICKS_HOST", accountScoped }));
+    const tokenUrl = buildDatabricksUrl(rawHost, "/oidc/v1/token");
+    const credentials = btoa(`${clientId}:${clientSecret}`);
+    const tokenResponse = await fetch(tokenUrl, {
+        method: "POST",
+        headers: {
+            Authorization: `Basic ${credentials}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: `grant_type=client_credentials&scope=${scope}`,
+    });
+    if (!tokenResponse.ok) {
+        const errorBody = await tokenResponse.text();
+        throw new Error(`Failed to obtain Databricks access token: ${tokenResponse.status} ${tokenResponse.statusText} - ${errorBody}`);
+    }
+    const responseData = await tokenResponse.json();
+    const parseResult = DatabricksTokenResponseSchema.safeParse(responseData);
+    if (!parseResult.success) {
+        throw new Error(`Invalid token response: ${parseResult.error.message}`);
+    }
+    return {
+        databricksAccessToken: parseResult.data.access_token,
+        databricksTokenExpiresIn: parseResult.data.expires_in,
+    };
+};
+
+export { ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER, FORWARDED_AUTHORIZATION_HEADER, getAccountId, getDatabricksAccessToken, getSecret, getUserToken };

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@trackunit/serverside-utils",
+  "version": "0.0.2",
+  "repository": "https://github.com/Trackunit/manager",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=24.x"
+  },
+  "dependencies": {
+    "hono": "^4.12.5",
+    "jwt-decode": "^3.1.2",
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "hono": "^4.12.5",
+    "jwt-decode": "^3.1.2",
+    "zod": "^3.23.8"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/get-account-id.d.ts

@@ -0,0 +1,35 @@
+import { Context } from "hono";
+type GetAccountIdOptions = {
+    /** Hono request context */
+    context: Context;
+};
+type AccountIdResult = {
+    /** The effective account ID to use (prefers assumedAccountId over accountId) */
+    accountId: string;
+    /** The assumed account ID from the token, present when acting on behalf of another account */
+    assumedAccountId: string | undefined;
+    /** The original account ID from the token (the token owner's account) */
+    tokenAccountId: string | undefined;
+};
+/**
+ * Extracts the account ID from the user token in the request.
+ *
+ * Trackunit tokens may contain both `accountId` (token owner) and `assumedAccountId`
+ * (account being acted upon). This function returns the effective account ID,
+ * preferring `assumedAccountId` when present.
+ *
+ * @param options - The options object
+ * @param options.context - Hono request context
+ * @returns {AccountIdResult} The effective account ID and the raw assumedAccountId (if present)
+ * @throws Error if no user token is found or the token has no account ID
+ * @example
+ * ```typescript
+ * // Simple usage — just get the effective account ID:
+ * const { accountId } = getAccountId({ context: c });
+ *
+ * // When you need to know if the user is assuming an account:
+ * const { accountId, assumedAccountId } = getAccountId({ context: c });
+ * ```
+ */
+export declare const getAccountId: ({ context }: GetAccountIdOptions) => AccountIdResult;
+export {};

package/src/get-databricks-access-token.d.ts

@@ -0,0 +1,42 @@
+import { Context } from "hono";
+/**
+ * The properties of the request to the Databricks token endpoint.
+ */
+export type GetDatabricksAccessTokenProps = {
+    /** The context of the request. */
+    context: Context;
+    /** The host of the Databricks instance. */
+    databricksHost?: string;
+    /** The client ID of the Databricks application. */
+    databricksClientId?: string;
+    /** The client secret of the Databricks application. */
+    databricksClientSecret?: string;
+    /** When true, fetches account-scoped secrets instead of app-level secrets. Requires a valid user token with an accountId. */
+    accountScoped?: boolean;
+    /**
+     * The scope of the request to the Databricks token endpoint.
+     * Defaults to all-apis.
+     *
+     * @see {@link https://docs.databricks.com/aws/en/dev-tools/auth/oauth-u2m#generate-an-account-level-access-token Generate an account-level access token docs}
+     */
+    scope?: string;
+};
+/**
+ * Obtains a Databricks OAuth access token using the client credentials flow.
+ *
+ * @example
+ *
+ * const { databricksAccessToken } = await getDatabricksAccessToken({ context: c });
+ * @param props - The properties of the request.
+ * @param props.context - The context of the request.
+ * @param props.databricksHost - The host of the Databricks instance.
+ * @param props.databricksClientId - The client ID of the Databricks application.
+ * @param props.databricksClientSecret - The client secret of the Databricks application.
+ * @param props.accountScoped - When true, fetches account-scoped secrets (requires user token with accountId)
+ * @param props.scope - The scope of the request to the Databricks token endpoint. Defaults to `all-apis`.@param options.accountScoped - When true, fetches account-scoped secrets (requires user token with accountId)
+ * @returns {Promise<{ databricksAccessToken: string; databricksTokenExpiresIn?: number }>} The access token and optional expiry in seconds.
+ */
+export declare const getDatabricksAccessToken: ({ context, databricksHost, databricksClientId, databricksClientSecret, accountScoped, scope, }: GetDatabricksAccessTokenProps) => Promise<{
+    databricksAccessToken: string;
+    databricksTokenExpiresIn?: number;
+}>;

package/src/get-secret.d.ts

@@ -0,0 +1,35 @@
+import { Context } from "hono";
+type GetSecretOptions<TSecretKey extends string> = {
+    /** Hono request context */
+    context: Context;
+    /** Key name of the secret (also used as env var name for local dev) */
+    secretKey: TSecretKey;
+    /** When true, fetches account-scoped secrets instead of app-level secrets. Requires a valid user token with an accountId. */
+    accountScoped?: boolean;
+};
+/**
+ * Fetches a secret from the SDK Server.
+ *
+ * By default fetches **app-level** secrets (`GET /secrets`).
+ * Pass `accountScoped: true` to fetch **account-scoped** secrets (`GET /secrets/:accountId`).
+ *
+ * For local development, set the secret as an environment variable with the same name
+ * as the secretKey (e.g., `API_KEY=xxx` in your `.env` file).
+ *
+ * @param options - The options object
+ * @param options.context - Hono request context
+ * @param options.secretKey - Key name of the secret
+ * @param options.accountScoped - When true, fetches account-scoped secrets (requires user token with accountId)
+ * @returns {Promise<string>} The secret value
+ * @throws Error if required headers or env vars are missing, or secret not found
+ * @example
+ * ```typescript
+ * // App-level secret (default)
+ * const apiKey = await getSecret({ context: c, secretKey: "API_KEY" });
+ *
+ * // Account-scoped secret
+ * const accountKey = await getSecret({ context: c, secretKey: "API_KEY", accountScoped: true });
+ * ```
+ */
+export declare const getSecret: <TSecretKey extends string>({ context, secretKey, accountScoped, }: GetSecretOptions<TSecretKey>) => Promise<string>;
+export {};

package/src/get-user-token.d.ts

@@ -0,0 +1,26 @@
+import { Context } from "hono";
+type GetUserTokenOptions = {
+    /** Hono request context */
+    context: Context;
+};
+/**
+ * Retrieves the user token from the request headers.
+ *
+ * @param options - The options object
+ * @param options.context - Hono request context
+ * @returns {string | undefined} The user token (without "Bearer " prefix), or undefined if not found
+ * @example
+ * ```typescript
+ * import { getUserToken } from "@trackunit/serverside-utils";
+ *
+ * app.get("/data", async (c) => {
+ *   const token = getUserToken({ context: c });
+ *   if (!token) {
+ *     return c.json({ error: "Unauthorized" }, 401);
+ *   }
+ *   // Use token for API calls...
+ * });
+ * ```
+ */
+export declare const getUserToken: ({ context }: GetUserTokenOptions) => string | undefined;
+export {};

package/src/headers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Header key for the account admin iris app token.
+ * Used by the SDK server to pass admin tokens to serverside functions.
+ *
+ * Uses vendor prefix "tu-" (Trackunit) per RFC 6648 which deprecated the "X-" convention.
+ */
+export declare const ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER = "tu-account-admin-iris-app-token";
+/**
+ * Header key for the forwarded authorization token.
+ * The original user authorization token is moved to this header.
+ *
+ * Uses vendor prefix "tu-" (Trackunit) per RFC 6648 which deprecated the "X-" convention.
+ */
+export declare const FORWARDED_AUTHORIZATION_HEADER = "tu-forwarded-authorization";

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export { getAccountId } from "./get-account-id";
+export { getDatabricksAccessToken, type GetDatabricksAccessTokenProps } from "./get-databricks-access-token";
+export { getSecret } from "./get-secret";
+export { getUserToken } from "./get-user-token";
+export { ACCOUNT_ADMIN_IRIS_APP_TOKEN_HEADER, FORWARDED_AUTHORIZATION_HEADER } from "./headers";

package/src/token-utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Removes the "Bearer " prefix from a token string if present.
+ *
+ * @param token - The token string, possibly prefixed with "Bearer "
+ * @returns {string} The token without the "Bearer " prefix
+ */
+export declare const stripBearerPrefix: (token: string) => string;