Agent doc: Notification JS SDK

Package

• Name: @spectra-platform/notification-sdk
• Version: 0.1.0
• Registry: GitHub Packages

Purpose

Notification JS SDK presents email verification and push device registration as notification experiences, even if the server producer is Delivery Platform.

API tree

Notification JS SDK
├─ setup
│  ├─ new SpectraNotificationClient(config)
│  └─ createSpectraNotificationClient(config)
├─ email
│  ├─ sendEmailCode(options)
│  └─ verifyEmailCode(options)
└─ push
   └─ registerForPush(options)

Public setup inputs

• projectId
• environment: test or live
• auth, usually an Auth SDK instance
• endpoint override only for advanced diagnostics

Secret Key exposure in browser/mobile SDK requires an explicit consuming-project architecture decision. Project Secret Keys are bound to test or live, shown once, and do not expire by date.

Required auth object and token boundary

• Pass the Auth JS SDK object as auth.
• sendEmailCode() uses an Auth-managed email service token.
• registerForPush() uses an Auth-managed notification service token.
• Browser/mobile code must not hold SMTP credentials, APNs keys, or FCM server keys. Secret Key exposure requires an explicit consuming-project architecture decision, and the raw value must not be logged. Secret Key expiry fields should not be added to SDK setup.

Agent integration order

1. Verify Auth SDK login, getSession(), and getAccessToken() first.

2. Create SpectraNotificationClient with projectId, environment, and auth.

3. Implement email code request with sendEmailCode().

4. Implement email code verification with verifyEmailCode().

5. Add push registration structure with registerForPush() only when the app has APNs/FCM provider tokens from the platform runtime.

6. Keep real device push delivery as a separate provider E2E gate.

Public operations

• sendEmailCode({ email, subject, text?, html?, expiresInSeconds?, metadata? }): requests a code using direct body fields.
• verifyEmailCode({ verificationId, code }): verifies a previously requested code.
• registerForPush({ platform, providerToken, appIdentifier, deviceId?, appInstanceId?, locale? }): registers APNs/FCM token using the notification service token.

templateId and templateVersion are advanced optional inputs for teams that already operate managed templates. Do not make a consuming app create a template for the first verification flow.

Consumer example

import { SpectraNotificationClient } from "@spectra-platform/notification-sdk";

const notification = new SpectraNotificationClient({
  projectId,
  environment: "test",
  auth,
});

const challenge = await notification.sendEmailCode({
  email,
  subject: "Your sign-in code",
  text: "Your code is {{code}}.",
});

await notification.verifyEmailCode({
  verificationId: challenge.verificationId,
  code,
});

Current caveats

• Operational SMTP and actual APNs/FCM device E2E are separate provider gates.
• Server-side bulk or operational sending should not be done from browser SDK. Use a backend-held environment-bound Project ID + Secret Key, and require the matching Email/Push service toggle to be enabled.
• Web Push is not part of the immediate MVP surface.

Escalate to Platform CS when

• Email code request or verification requires a Secret Key in browser/mobile code without an explicit consuming-project architecture decision.
• Email verification requires a templateId before a direct body path exists.
• The SDK cannot obtain email or notification service tokens through the injected Auth object.
• sendEmailCode()/verifyEmailCode() method names or response fields differ from the documented package surface.
• Push registration fails before provider-specific APNs/FCM delivery is involved.