@cloudstrife21/email-sdk

Server-side TypeScript client for the StrongStart email send API.

Scope

• Node.js server environments only
• POST /api/esp/v1/send-template
• Optional HMAC signing via x-signature
• Typed errors for non-2xx API responses

Install

npm install @cloudstrife21/email-sdk

Until it is published, you can consume the sibling package directly during local development:

npm install ../email-sdk

Environment variables

EMAIL_API_BASE_URL=https://email.strongstart.digital
EMAIL_API_KEY=k_live_xxx
EMAIL_CLIENT_ID=app_ytexas
EMAIL_HMAC_SECRET=sh_hmac_xxx

Usage

import { createEmailClient, emailClientConfigFromEnv, EmailApiError } from '@cloudstrife21/email-sdk';

const email = createEmailClient(emailClientConfigFromEnv(process.env));

try {
  const result = await email.sendTemplate({
    templateKey: 'welcome_email',
    to: '[email protected]',
    data: {
      name: 'Ada',
      ctaUrl: 'https://ytexas.org/welcome'
    },
    category: 'transactional'
  });

  console.log(result.id, result.status, result.requestId);
} catch (error) {
  if (error instanceof EmailApiError) {
    console.error(error.status, error.code, error.requestId, error.payload);
  }
  throw error;
}

API

createEmailClient(config)

Creates a client for the StrongStart send endpoint.

Config fields:

• baseUrl: API origin such as https://email.strongstart.digital
• apiKey: tenant-scoped API key sent as x-api-key
• clientId: application identifier expected by the API
• hmacSecret: optional request-signing secret
• fetch: optional fetch implementation override
• defaultHeaders: optional headers applied to every request
• generateIdempotencyKey: optional idempotency key factory

email.sendTemplate(request, options?)

Supported request fields:

• templateId or templateKey
• optional version when using templateKey
• to
• optional data
• optional subject
• optional senderDomain
• optional category
• optional cc and bcc for forward compatibility with the API contract

Options:

• idempotencyKey
• requestId
• headers
• signal

Errors

Non-2xx responses throw EmailApiError with:

• status
• code
• requestId
• payload

Build

npm run build

Test

npm test

Release checklist

Run these steps from the email-sdk directory before publishing:

# 1) Authenticate to npm (required)
npm whoami

# 2) Verify package identity and publish access
npm pkg get name version publishConfig.access

# 3) Run quality gates
npm test
npm run build

# 4) Verify packed contents
npm pack --dry-run

# 5) Publish
npm publish --access public

After publishing, verify the package is visible:

npm view @cloudstrife21/email-sdk version
npm view @cloudstrife21/email-sdk dist-tags --json