@disconetwork/core 0.0.4 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,240 @@
1
+ # @disconetwork/core
2
+
3
+ The JavaScript/TypeScript SDK for the Disco recommendations and events APIs.
4
+ Works in any runtime with `fetch` — Node, edge, and the browser.
5
+
6
+ `DiscoClient` talks to the Disco partners gateway directly:
7
+
8
+ - **Recommendations** — fetch personalized offers for a placement.
9
+ - **Events** — report displays, views, and clicks back to Disco via a
10
+ session-bound tracker.
11
+
12
+ It gives you a typed request/response surface, validates both sides against the
13
+ API schema, and normalizes failures into a small, catchable error hierarchy.
14
+
15
+ ## Installation
16
+
17
+ ```sh
18
+ npm install @disconetwork/core
19
+ # or: pnpm add @disconetwork/core / yarn add @disconetwork/core
20
+ ```
21
+
22
+ Requires Node 20+ (or any runtime with a global `fetch`). `zod` is the only
23
+ runtime dependency.
24
+
25
+ ## Authentication
26
+
27
+ Authenticate with a **scoped public API key**:
28
+
29
+ | Prefix | Environment |
30
+ | -------------------- | ----------------- |
31
+ | `disco_pk_live_…` | production |
32
+ | `disco_pk_sandbox_…` | staging / sandbox |
33
+
34
+ Anything else — including a **secret** (`disco_sk_…`) key — is rejected:
35
+ `DiscoClient` is public-key only.
36
+
37
+ ## Quick start
38
+
39
+ ```ts
40
+ import { DiscoClient } from "@disconetwork/core";
41
+
42
+ const disco = new DiscoClient({ apiKey: process.env.DISCO_API_KEY! });
43
+
44
+ const { data, tracker } = await disco.getRecommendationsWithTracker({
45
+ userDetails: { email: "shopper@example.com" },
46
+ placementDetails: { displayMode: "OVERLAY", view: "THANK_YOU" },
47
+ });
48
+
49
+ // Report that the widget loaded.
50
+ tracker.track({ type: "WIDGET_LOAD" });
51
+
52
+ // Render recommendations from the normalized response.
53
+ for (const [groupKey, entries] of Object.entries(data.recommendationGroups)) {
54
+ for (const entry of entries) {
55
+ const rec = data.recommendations[entry.offerId];
56
+ console.log(rec.advertiser.name, "—", rec.offer.heading);
57
+ }
58
+ }
59
+ ```
60
+
61
+ ## Creating a client
62
+
63
+ ```ts
64
+ const disco = new DiscoClient({
65
+ apiKey: "disco_pk_live_…", // required; selects the environment
66
+ apiVersion: "1.0.0", // optional; sent as the X-API-Version header (default "1.0.0")
67
+ fetch: customFetch, // optional; defaults to globalThis.fetch
68
+ });
69
+ ```
70
+
71
+ `DiscoClientConfig`:
72
+
73
+ | Field | Type | Required | Description |
74
+ | ------------ | -------------- | -------- | --------------------------------------------------------------------- |
75
+ | `apiKey` | `string` | yes | Scoped public key. Prefix selects production vs. staging. |
76
+ | `apiVersion` | `string` | no | Value for the required `X-API-Version` header. Defaults to `"1.0.0"`. |
77
+ | `fetch` | `typeof fetch` | no | Custom fetch implementation. Defaults to the global `fetch`. |
78
+
79
+ ## Fetching recommendations
80
+
81
+ ### `getRecommendations(request, options?)`
82
+
83
+ Returns a `Promise<RecommendationsResponse>`.
84
+
85
+ ```ts
86
+ import type { RecommendationsRequest } from "@disconetwork/core";
87
+
88
+ const request: RecommendationsRequest = {
89
+ // Must carry at least one identifier: email, emailHash, externalGuid, or phone.
90
+ userDetails: {
91
+ email: "shopper@example.com",
92
+ firstName: "Ada",
93
+ gender: "FEMALE",
94
+ },
95
+ placementDetails: {
96
+ displayMode: "OVERLAY",
97
+ view: "THANK_YOU",
98
+ },
99
+ orderDetails: {
100
+ orderId: "order-123",
101
+ costDetails: { amount: 4999, currencyCode: "USD" },
102
+ },
103
+ purchases: [{ name: "Wireless Mouse", quantity: 1, productId: "sku-9" }],
104
+ };
105
+
106
+ const data = await disco.getRecommendations(request);
107
+ ```
108
+
109
+ The response is returned as a set of normalized maps for you to join and
110
+ transform as you see fit:
111
+
112
+ - `data.recommendations` — `offerId → Recommendation` (`{ advertiser, offer }`).
113
+ - `data.recommendationGroups` — `groupKey → RecommendationGroupEntry[]`, the
114
+ ordered entries referencing offer ids.
115
+ - `data.recommendationGroupProperties` — `groupKey → RecommendationGroupProperty`
116
+ (heading / slot context).
117
+ - `data.footer` — attribution and privacy-policy copy you must surface.
118
+ - `data.sessionId` — pass this to `createTrackingManager` to report events.
119
+
120
+ Pass `options.signal` to cancel an in-flight request; an aborted request rejects
121
+ with the native `AbortError` (see [Error handling](#error-handling)).
122
+
123
+ ### `getRecommendationsWithTracker(request, options?)`
124
+
125
+ Convenience for the common case: fetch recommendations **and** create a tracker
126
+ already bound to the response's session, in one call. Returns
127
+ `{ data, tracker }`. The tracker inherits the client's API key and environment.
128
+
129
+ ```ts
130
+ const { data, tracker } = await disco.getRecommendationsWithTracker(request);
131
+ ```
132
+
133
+ ## Tracking events
134
+
135
+ A tracker is bound to one recommendations **session**. Create it from a response's
136
+ `sessionId` (or use `getRecommendationsWithTracker` to get one back automatically):
137
+
138
+ ```ts
139
+ const tracker = disco.createTrackingManager(data.sessionId);
140
+ ```
141
+
142
+ `tracker.track(event)` is **fire-and-forget** — it never throws and returns
143
+ `void`. Failures are logged via `console.error`. `WIDGET_DISPLAY`,
144
+ `WIDGET_VIEW`, `BRAND_DISPLAY`, and `BRAND_VIEW` are automatically deduped
145
+ per-session, so re-emitting them for the same brand is a no-op.
146
+
147
+ ```ts
148
+ // Widget lifecycle — no extra fields.
149
+ tracker.track({ type: "WIDGET_LOAD" });
150
+ tracker.track({ type: "WIDGET_DISPLAY" });
151
+ tracker.track({ type: "WIDGET_VIEW" });
152
+
153
+ // Brand visibility — requires the brand and where it rendered.
154
+ tracker.track({
155
+ type: "BRAND_VIEW",
156
+ brand: { offerId, advertiserId, insertionId },
157
+ target: "INLINE_SLOT",
158
+ });
159
+
160
+ // Brand click.
161
+ tracker.track({
162
+ type: "BRAND_CLICK",
163
+ brand: { offerId, advertiserId, insertionId },
164
+ target: "INLINE_ASSET_TILE",
165
+ assetId: "ast_1", // optional
166
+ });
167
+
168
+ // Product events.
169
+ tracker.track({
170
+ type: "PRODUCT_CLICK",
171
+ product: { productId: "sku-9" },
172
+ brand: { offerId, advertiserId, insertionId },
173
+ target: "INLINE_TILE",
174
+ });
175
+
176
+ // Non-brand UI interactions.
177
+ tracker.track({ type: "ELEMENT_CLICK", target: "CLOSE_BUTTON" });
178
+ ```
179
+
180
+ `brand` identifies a recommendation instance — `offerId`, `advertiserId`, and
181
+ `insertionId` come straight from a `RecommendationGroupEntry`. The `insertionId`
182
+ is the unique-per-render id used for dedup. Every event also accepts an optional
183
+ `placement` (`{ displayMode?, view?, layoutId? }`) for placement context.
184
+
185
+ `session_id` and the event timestamp are stamped automatically — you supply only
186
+ the event-specific fields above. The full set of event types and targets is
187
+ described by the exported `EventPayload` type.
188
+
189
+ ## Error handling
190
+
191
+ Every failure the client raises (except cancellation) extends `DiscoError`, so
192
+ you can catch the base class to handle any SDK error, or narrow to a subclass:
193
+
194
+ ```ts
195
+ import {
196
+ DiscoError,
197
+ DiscoApiError,
198
+ DiscoNetworkError,
199
+ DiscoValidationError,
200
+ } from "@disconetwork/core";
201
+
202
+ try {
203
+ const data = await disco.getRecommendations(request);
204
+ } catch (err) {
205
+ if (err instanceof DiscoApiError) {
206
+ // Non-2xx response. err.status, err.statusText, err.body
207
+ } else if (err instanceof DiscoValidationError) {
208
+ // Request/response failed schema validation. err.cause (ZodError), err.rawValue
209
+ } else if (err instanceof DiscoNetworkError) {
210
+ // Request never reached the server (DNS, timeout, connection reset). err.cause
211
+ } else if (err instanceof DiscoError) {
212
+ // Any other SDK error.
213
+ } else if (err instanceof Error && err.name === "AbortError") {
214
+ // Cancellation via AbortSignal — intentionally NOT a DiscoError.
215
+ }
216
+ }
217
+ ```
218
+
219
+ | Error | Thrown when | Notable fields |
220
+ | ---------------------- | -------------------------------------------------- | -------------------------------- |
221
+ | `DiscoApiError` | The API returns a non-2xx status. | `status`, `statusText`, `body` |
222
+ | `DiscoValidationError` | Request or response data fails schema validation. | `cause` (`ZodError`), `rawValue` |
223
+ | `DiscoNetworkError` | The request never completes (network/DNS/timeout). | `cause` |
224
+ | `DiscoError` | Abstract base of all of the above. | — |
225
+
226
+ A request aborted via `AbortSignal` rejects with the native `AbortError`, which
227
+ is deliberately **not** a `DiscoError` — detect it with `err.name === "AbortError"`.
228
+
229
+ ## TypeScript
230
+
231
+ The package ships full type definitions, so the entire request, response, and
232
+ event surface is discoverable through your editor's autocomplete — including the
233
+ allowed values for fields like `displayMode`, `view`, and the event `type`. Build
234
+ requests and events as object literals; they're type-checked against the schema
235
+ as you write them. Import `RecommendationsRequest` / `RecommendationsResponse`
236
+ (and their pieces) when you need to name a type explicitly.
237
+
238
+ ## License
239
+
240
+ MIT