Lamen Client SDK

Browser-safe JavaScript SDK for Lamen publishable-key integrations, with native mobile header support for Android and iOS publishable keys.

This package currently exposes two client-side services:

• athena for event ingestion with a publishable key
• maps for fetching hosted map styles

Package

• Package name: lamen-client
• Current version: 0.1.4
• Runtime: modern browsers or any runtime with fetch

Installation

npm install lamen-client

Initialize

Web

import { LamenClient } from "lamen-client";

const lamen = new LamenClient({
  publishableKey: "pk_live_web_...",
  appId: "com.company.web", // optional metadata
});

Android

import { LamenClient } from "lamen-client";

const lamen = new LamenClient({
  publishableKey: "pk_live_android_...",
  androidPackageName: "com.company.app",
  androidCertFingerprint: "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD",
});

iOS

import { LamenClient } from "lamen-client";

const lamen = new LamenClient({
  publishableKey: "pk_live_ios_...",
  iosBundleIdentifier: "com.company.app",
});

Config

LamenClient accepts:

• publishableKey string required
• baseUrl string optional, defaults to https://api.lamen.dev
• appId string optional, sent as x-app-id for legacy metadata and older web integrations
• androidPackageName string optional, sent as x-android-package
• androidCertFingerprint string optional, sent as x-android-cert
• iosBundleIdentifier string optional, sent as x-ios-bundle-identifier
• timeoutMs number optional, defaults to 10000
• maxRetries number optional, defaults to 2

Rules:

• androidPackageName and androidCertFingerprint must be provided together.
• iosBundleIdentifier cannot be combined with Android native identifiers on the same client instance.
• appId remains optional metadata. It is not a substitute for Android or iOS restriction headers.

Authentication is handled with the x-publishable-key header. Do not pass a secret API key to this SDK.

Key model

Publishable keys are both service-specific and client-surface-specific.

Examples:

• A web Athena integration uses one web Athena key.
• A native mobile app that uses Athena and Maps on both Android and iOS usually needs four keys:
  • Android Athena
  • iOS Athena
  • Android Maps
  • iOS Maps

Athena

Use lamen.athena.ingestEvent(...) to send client-side analytics events.

await lamen.athena.ingestEvent({
  external_user_id: "user_123",
  event_name: "signup_completed",
  occurred_at: new Date(),
  properties: {
    plan: "starter",
  },
});

Request shape:

• external_user_id string required
• event_name string required
• occurred_at Date | string required
• properties Record<string, any> optional
• idempotency_key string optional

Response shape:

type AthenaIngestResponse = {
  ok: boolean;
  deduplicated?: boolean | null;
};

Notes:

• If idempotency_key is omitted, the SDK generates one automatically.
• Athena retries retryable API errors on 408, 429, 500, 502, 503, and 504.
• Timeout errors are raised as a plain Error with message Athena request timed out.

Maps

Use lamen.maps.getStyle(...) to fetch a style document for a tileset.

const style = await lamen.maps.getStyle();

const style = await lamen.maps.getStyle("uk");

getStyle defaults to the uk tileset and returns the style field from the API response.

Errors

Athena errors:

• AthenaError
• AthenaApiError

Maps errors:

• MapsError

Example:

import { AthenaApiError, MapsError } from "lamen-client";

try {
  await lamen.maps.getStyle("uk");
} catch (error) {
  if (error instanceof MapsError) {
    console.error(error.status, error.message);
  }

  if (error instanceof AthenaApiError) {
    console.error(error.status, error.body);
  }
}

Exports

Top-level exports:

• LamenClient
• AthenaError
• AthenaApiError
• MapsClient
• ClientConfig
• Athena ingest types

Current Scope

This SDK does not include the server-side messaging, storage, stream, or geocoding APIs. For secret-key backend usage, use the Node or Python SDK instead.