Molecule.dev

← All @molecule/* packages · App templates

@molecule/api-activity-http

Provider bond · activity · API (Node) · v1.0.1 · Apache-2.0

Generic HTTP activity sink — POSTs activity events to a configured ingest endpoint

npm install @molecule/api-activity-http

npm · Source on GitHub · Implements @molecule/api-activity

How it works

@molecule/api-activity-http is a provider bond on the API (Node) side: it implements the activity core interface (@molecule/api-activity) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { setSink } from '@molecule/api-activity'
import { createHttpSink } from '@molecule/api-activity-http'

setSink(createHttpSink({ url: 'https://my-app.example/v1/activity' }))

Works with: @molecule/api-activity, @molecule/api-logger, @molecule/api-secrets

Secrets: MOLECULE_ACTIVITY_URL (optional)

Reference

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Generic HTTP activity sink.

POSTs captured activity events to a configured ingest endpoint (the url option or the MOLECULE_ACTIVITY_URL env var). No endpoint is assumed — when none is configured the sink no-ops, so an unconfigured consumer never silently phones home. Best-effort — never throws on failure.

Quick Start

import { setSink } from '@molecule/api-activity'
import { createHttpSink } from '@molecule/api-activity-http'

setSink(createHttpSink({ url: 'https://my-app.example/v1/activity' }))

Type

provider

Installation

npm install @molecule/api-activity-http @molecule/api-activity @molecule/api-logger @molecule/api-secrets

API

Interfaces

HttpActivitySinkOptions

Options for the HTTP activity sink.

interface HttpActivitySinkOptions {
  /**
   * The activity endpoint URL. Falls back to the `MOLECULE_ACTIVITY_URL` env
   * var. There is no built-in default — when neither is set the sink no-ops, so
   * an unconfigured generic consumer never POSTs to an assumed destination.
   */
  url?: string

  /**
   * The app's runtime vault token, sent as a bearer token.
   * Defaults to the `MOLECULE_VAULT_TOKEN` env var.
   */
  token?: string

  /**
   * The app id for the configured endpoint, sent as the `X-Molecule-App-Id`
   * header (omitted when unset). Defaults to the `MOLECULE_APP_ID` env var.
   */
  appId?: string
}

Functions

createHttpSink(options)

Creates an HTTP activity sink that POSTs each event to the configured ingest endpoint.

Best-effort: an unconfigured endpoint is skipped (debug-logged), and a failed POST (or a thrown fetch) is caught and logged, never rethrown, so capture providers can record unconditionally.

function createHttpSink(options?: HttpActivitySinkOptions): ActivitySink
  • options — Endpoint URL, runtime token, and app id. Each falls back to its corresponding MOLECULE_* env var, resolved per-request. With no URL configured the sink does nothing — it never assumes a destination.

Returns: An {@link ActivitySink} backed by an HTTP POST.

Constants

activityHttpSecretDefinitions

Secret definitions required by the HTTP activity sink bond.

const activityHttpSecretDefinitions: SecretDefinition[]

provider

Default HTTP activity sink instance, configured from environment variables.

const provider: ActivitySink

Core Interface

Implements @molecule/api-activity interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setSink } from '@molecule/api-activity'
import { provider } from '@molecule/api-activity-http'

export function setupActivityHttp(): void {
  setSink(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-activity ^1.0.1
  • @molecule/api-logger ^1.0.1
  • @molecule/api-secrets ^1.0.1

Environment Variables

  • MOLECULE_ACTIVITY_URL (optional) — molecule.dev activity capture URL
    • Provisioned automatically in molecule.dev sandboxes — manual setup only needed outside the platform.
    • Setup: Endpoint for captured side effects (emails/SMS/webhooks) in molecule.dev sandboxes.

Runtime Dependencies

  • @molecule/api-activity
  • @molecule/api-logger
  • @molecule/api-secrets