@lobsterhoney/sdk

Thin browser metrics loader. A tiny bootstrap that fetches your per-site configuration at runtime and hands off to a versioned module served from your metrics endpoint. No configuration lives in this package.

Install

npm install @lobsterhoney/sdk

Or load from your endpoint via a script tag.

Usage

Script tag (auto-init)

<script src="https://your-endpoint.example.com/loader.js" data-key="your-site-key"></script>

The loader auto-initializes when data-key is present. The endpoint is inferred from the script's src origin.

Programmatic

import { init } from '@lobsterhoney/sdk';

await init({
  key: 'your-site-key',
  endpoint: 'https://your-endpoint.example.com',
});

Configuration

interface InitOptions {
  key: string;         // Site key (8-128 chars, alphanumeric + _ -)
  endpoint?: string;   // Endpoint origin; inferred from the script src if omitted
}

Content Security Policy

The loader fetches its runtime configuration from your endpoint and then loads a module from that same origin. If your site sends a Content-Security-Policy header, allow your endpoint origin in both directives:

Content-Security-Policy:
  script-src  'self' https://your-endpoint.example.com;
  connect-src 'self' https://your-endpoint.example.com;

• connect-src covers the runtime config fetch and the metrics POST.
• script-src covers the dynamically imported runtime module.

Replace your-endpoint.example.com with the endpoint origin issued at onboarding. No blob: or 'unsafe-eval' is required — the loader imports a plain HTTPS module URL and never evaluates strings.

How it loads

• The loader requests your site config from the endpoint over HTTPS.
• The runtime module URL in that config is validated to be HTTPS and on the endpoint origin (or a subdomain of it) before it is imported.
• The module URL is versioned and immutable, so it is cached long-term and never changes for a given version.

Security notes

• Zero runtime dependencies; ships ESM, UMD, and a minified UMD bundle for CDN <script> use.
• Endpoint is origin-validated before any request: it must be HTTPS and either same-origin or a subdomain of the configured base. A mismatched endpoint is rejected.
• Site-key format is validated on auto-init (8-128 chars, alphanumeric plus _/-).
• No eval, no new Function, no blob: — the runtime module is loaded by a native dynamic import() of a validated HTTPS URL.
• Auto-init failures are swallowed so they never surface in your page's error handlers.

License

MIT