SeekAPI Node.js SDK

SDK for building SeekAPI workers in Node.js (Lambda). Handles input (fetch from presigned URL) and output (push JSON and files), charge (per-event billing), with a minimal Lambda return contract.

• Zero dependencies — uses only Node built-ins.
• Node 18+ — works in AWS Lambda runtimes.

Install

npm install seekapi

Quick start (recommended)

Use run() so the SDK handles input, output, and errors. You only implement a function from input → output:

const { run } = require("seekapi");

exports.handler = async (event, context) =>
  run(event, context, (input) => ({
    message: `hello ${input.name || "world"}`,
  }));

Async worker:

const { run } = require("seekapi");

exports.handler = (event, context) =>
  run(event, context, async (input) => {
    const data = await fetchSomething(input.url);
    return { count: data.length };
  });

Low-level API

When you need more control (e.g. multiple pushData calls, pushFile, or charge):

const {
  getInput,
  createContext,
  pushData,
  pushFile,
  registerRequestId,
  charge,
  success,
  failure,
} = require("seekapi");

exports.handler = async (event, context) => {
  const requestId = context && context.awsRequestId;
  const jobUuid = (event.job_uuid || "").trim();
  if (requestId && jobUuid) registerRequestId(jobUuid, requestId);

  const ctx = createContext(event);
  try {
    const inputData = await getInput(event);
    await pushData(ctx, { result: "ok" });
    return success(requestId);
  } catch (e) {
    return failure("WORKER_ERROR", e.message || String(e), requestId);
  }
};

API reference

| Function | Description | |----------|-------------| | getInput(event, timeoutOrOpts?) | Promise: fetch and parse job input JSON from event.input_presigned_url. Second arg: timeout in seconds (default 10), or { timeout: seconds }. Rejects with MissingInputError if URL missing; otherwise Error on HTTP/timeout/JSON errors. | | createContext(event) | Build context object for pushData / pushFile / charge: job_uuid, execution_token, api_base, secret (same shape as the Python SDK). | | charge(context, idempotencyKey, count?, timeoutSeconds?, justification?) | Promise: record metered billing units (per_event). Returns parsed API JSON. Rejects if context is incomplete or HTTP error. | | pushData(context, data, type?, timeoutSeconds?) | Promise: append JSON to the job (type default "json"; default timeout 8 seconds). No-op if env/context incomplete. | | pushFile(context, name, localPath, contentType?, timeoutSeconds?) | Promise: push a file to the job temp files (default timeout 15 seconds). | | registerRequestId(jobUuid, requestId, timeoutSeconds?) | Register Lambda request_id for live logs (no-op if env not set; default timeout 3 seconds). | | success(requestId?) | Return { ok: true, request_id? }. | | failure(code, message, requestId?) | Return { ok: false, error: { code, message }, request_id? }. | | run(event, context, userFn) | Promise: getInput → userFn(input) → pushData → success; on error → failure. Caps network timeouts to remaining Lambda time (same behavior as the Python SDK). |

Aliases (same as Python names): get_input, create_context, register_request_id, push_data, push_file.

Environment (set by the platform)

• WORKER_API_BASE_URL — backend base URL for push, charge, and registerRequestId.
• WORKER_INTERNAL_SECRET — secret for internal API auth.

In production, WORKER_API_BASE_URL should target https://api.seek-api.com (injected automatically by the SeekAPI deployment flow).

Errors

• MissingInputError — event has no input_presigned_url (subclass of Error).
• Error — input fetch failed (HTTP, timeout, invalid JSON); message is descriptive.

Publishing to npm

From the package directory:

npm version patch   # or minor/major
npm publish

Ensure you are logged in (npm login) and the package name is available on npm.

Migration from 1.x

• createContext retourne désormais les clés job_uuid, execution_token, api_base, secret (comme le SDK Python), et non plus jobUuid / apiBase en camelCase.
• getInput : le délai est exprimé en secondes (défaut 10), plus en millisecondes.
• successWithOutput a été retiré (non présent dans le SDK Python) ; enchaînez await pushData(ctx, data) puis return success(requestId).