@cross-deck/node 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to `@cross-deck/node` will be documented here. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-05-12
+
+Initial server SDK release.
+
+### Added
+
+- Separate `@cross-deck/node` package with no browser assumptions.
+- `CrossdeckServer` constructor with secret-key validation.
+- Secret-key HTTP transport with typed `CrossdeckError` handling.
+- Web-parity sanitisation for traits and event properties, plus a transport
+  backstop that converts serialization failures into stable `CrossdeckError`s.
+- `identify()` / `aliasIdentity()` for server-side identity linking.
+- `forget()` for server-side GDPR/CCPA deletion requests.
+- `getEntitlements()` by `customerId`, `userId`, or `anonymousId`.
+- `getCustomerEntitlements(customerId)` server-only direct lookup route.
+- `track()` and `ingest()` for explicit server-side event ingest.
+- `syncPurchases()` for Apple signed purchase forwarding.
+- `grantEntitlement()` and `revokeEntitlement()` server-side manual overrides.
+- `getAuditEntry()` for server-side audit-log reads.
+- Dual ESM/CJS build.
+- Strict TypeScript + Vitest coverage for transport and public method routing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crossdeck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# @cross-deck/node
+
+The Crossdeck server SDK for Node.js.
+
+This is the **secret-key** SDK: server-only, no browser assumptions, no
+auto-tracking, no local state. It wraps the real HTTP surface for
+entitlements, identity aliasing, event ingest, purchase forwarding, manual
+entitlement overrides, and audit reads.
+
+```bash
+npm install @cross-deck/node
+```
+
+## Quick start
+
+```ts
+import { CrossdeckServer } from "@cross-deck/node";
+
+const crossdeck = new CrossdeckServer({
+  secretKey: process.env.CROSSDECK_SECRET_KEY!,
+});
+
+const entitlements = await crossdeck.getEntitlements({ userId: "user_847" });
+
+await crossdeck.track({
+  name: "invoice.retry_started",
+  developerUserId: "user_847",
+  properties: { invoiceId: "inv_123" },
+});
+```
+
+## What this SDK is for
+
+- **Server-side entitlement reads.** Query by `customerId`, `userId`, or `anonymousId`.
+- **Identity graph writes.** Alias a known `anonymousId` to your stable `userId`.
+- **Telemetry from jobs and backends.** Send events from cron jobs, webhooks, workers, and admin tools.
+- **Fast purchase forwarding.** Push signed Apple purchase evidence directly.
+- **Manual entitlement controls.** Grant or revoke an entitlement with a reason.
+- **Audit lookup.** Read one audit-log entry by event ID.
+
+## What this SDK is not
+
+- Not for browsers.
+- Not a wrapper around the web SDK.
+- Not a stateful singleton that keeps identity or a queue in memory.
+- Not an auto-tracker. Every server call is explicit.
+
+## Constructing the client
+
+```ts
+import { CrossdeckServer } from "@cross-deck/node";
+
+const crossdeck = new CrossdeckServer({
+  secretKey: process.env.CROSSDECK_SECRET_KEY!,
+  baseUrl: "https://api.cross-deck.com/v1", // optional
+  timeoutMs: 15_000,                        // optional
+  appId: "app_web_xxx",                     // optional informational event envelope field
+});
+```
+
+`secretKey` must start with `cd_sk_`. The constructor throws immediately on
+an invalid key prefix so a server misconfiguration fails at boot, not under
+load.
+
+## Identity
+
+### `await crossdeck.identify(userId, anonymousId, options?)`
+
+Alias a pre-login `anonymousId` to your stable user ID. This is the same
+identity graph the web SDK uses, just called explicitly from your backend.
+
+```ts
+await crossdeck.identify("user_847", "anon_123", {
+  email: "wes@example.com",
+  traits: { plan: "pro", region: "za" },
+});
+```
+
+`identify()` is a convenience alias for `aliasIdentity(...)`.
+
+Traits are sanitised before send with the same rules as `@cross-deck/web`:
+`BigInt` becomes a string, circular refs become `"[circular]"`, `Map`/`Set`
+normalise to JSON-friendly shapes, and functions/symbols/`undefined` are dropped.
+
+### `await crossdeck.forget(hints)`
+
+Queue GDPR/CCPA deletion by `customerId`, `userId`, or `anonymousId`.
+
+```ts
+await crossdeck.forget({ customerId: "cdcust_123" });
+```
+
+## Entitlements
+
+### `await crossdeck.getEntitlements(hints)`
+
+Read entitlements by any supported identity hint.
+
+```ts
+const result = await crossdeck.getEntitlements({ userId: "user_847" });
+console.log(result.data.map((e) => e.key));
+```
+
+### `await crossdeck.getCustomerEntitlements(customerId)`
+
+Server-only direct lookup by canonical Crossdeck customer ID.
+
+```ts
+const result = await crossdeck.getCustomerEntitlements("cdcust_123");
+```
+
+### `await crossdeck.grantEntitlement(input)`
+
+Manually grant an entitlement.
+
+```ts
+await crossdeck.grantEntitlement({
+  customerId: "cdcust_123",
+  entitlementKey: "pro",
+  duration: "P30D",
+  reason: "Support recovery after billing incident",
+});
+```
+
+### `await crossdeck.revokeEntitlement(input)`
+
+Manually revoke an entitlement.
+
+```ts
+await crossdeck.revokeEntitlement({
+  customerId: "cdcust_123",
+  entitlementKey: "pro",
+  reason: "Chargeback",
+});
+```
+
+## Events
+
+### `await crossdeck.track(event)`
+
+Send one event immediately.
+
+```ts
+await crossdeck.track({
+  name: "support.refund_issued",
+  crossdeckCustomerId: "cdcust_123",
+  properties: { ticketId: "ticket_987" },
+});
+```
+
+Identity is required on every event. Provide at least one of:
+
+- `developerUserId`
+- `anonymousId`
+- `crossdeckCustomerId`
+
+### `await crossdeck.ingest(events)`
+
+Send a batch in one call.
+
+```ts
+await crossdeck.ingest([
+  {
+    name: "job.started",
+    developerUserId: "user_847",
+    properties: { job: "daily-mrr-reconcile" },
+  },
+  {
+    name: "job.completed",
+    developerUserId: "user_847",
+    properties: { job: "daily-mrr-reconcile", durationMs: 842 },
+  },
+]);
+```
+
+The SDK auto-mints `eventId` and `timestamp` if you omit them.
+
+Event `properties` are sanitised with the same contract as the web SDK before
+they hit the wire, so one bad backend-shaped object cannot crash request
+serialization.
+
+## Purchases
+
+### `await crossdeck.syncPurchases(input)`
+
+Forward Apple signed purchase evidence to Crossdeck.
+
+```ts
+await crossdeck.syncPurchases({
+  signedTransactionInfo: transactionJws,
+  signedRenewalInfo: renewalJws,
+});
+```
+
+## Audit
+
+### `await crossdeck.getAuditEntry(eventId)`
+
+Read one audit row by event ID.
+
+```ts
+const audit = await crossdeck.getAuditEntry("srv_grant_123");
+console.log(audit.decision, audit.reason);
+```
+
+## Errors
+
+Every non-2xx response is normalised to `CrossdeckError`:
+
+```ts
+import { CrossdeckError } from "@cross-deck/node";
+
+try {
+  await crossdeck.getEntitlements({ userId: "user_847" });
+} catch (err) {
+  if (err instanceof CrossdeckError) {
+    console.error(err.type, err.code, err.requestId);
+  }
+}
+```
+
+The error fields mirror the backend envelope:
+
+- `type`
+- `code`
+- `message`
+- `requestId`
+- `status`
+- `retryAfterMs`
+
+## Node version
+
+Node 18+ is required. The SDK uses the platform `fetch` implementation and
+does not ship an HTTP dependency.
+
+## License
+
+MIT