@ethicly/react-native 0.0.0-stage → 0.2.0

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.
Files changed (70) hide show
  1. package/CHANGELOG.md +75 -0
  2. package/LICENSE +21 -0
  3. package/README.md +313 -2
  4. package/core/package.json +6 -0
  5. package/interstitial/package.json +6 -0
  6. package/lib/commonjs/core/adapters.js +287 -0
  7. package/lib/commonjs/core/beacons.js +70 -0
  8. package/lib/commonjs/core/cache.js +206 -0
  9. package/lib/commonjs/core/click.js +19 -0
  10. package/lib/commonjs/core/client.js +489 -0
  11. package/lib/commonjs/core/config.js +113 -0
  12. package/lib/commonjs/core/http.js +115 -0
  13. package/lib/commonjs/core/index.js +20 -0
  14. package/lib/commonjs/core/outbox.js +192 -0
  15. package/lib/commonjs/core/tracker.js +374 -0
  16. package/lib/commonjs/core/types.js +4 -0
  17. package/lib/commonjs/index.js +22 -0
  18. package/lib/commonjs/interstitial.js +7 -0
  19. package/lib/commonjs/react/EthiclyInterstitial.js +286 -0
  20. package/lib/commonjs/react/useEthiclyInterstitial.js +54 -0
  21. package/lib/commonjs/version.js +5 -0
  22. package/lib/module/core/adapters.js +276 -0
  23. package/lib/module/core/beacons.js +64 -0
  24. package/lib/module/core/cache.js +202 -0
  25. package/lib/module/core/click.js +15 -0
  26. package/lib/module/core/client.js +485 -0
  27. package/lib/module/core/config.js +104 -0
  28. package/lib/module/core/http.js +105 -0
  29. package/lib/module/core/index.js +6 -0
  30. package/lib/module/core/outbox.js +186 -0
  31. package/lib/module/core/tracker.js +370 -0
  32. package/lib/module/core/types.js +3 -0
  33. package/lib/module/index.js +4 -0
  34. package/lib/module/interstitial.js +3 -0
  35. package/lib/module/react/EthiclyInterstitial.js +260 -0
  36. package/lib/module/react/useEthiclyInterstitial.js +51 -0
  37. package/lib/module/version.js +2 -0
  38. package/lib/typescript/core/adapters.d.ts +138 -0
  39. package/lib/typescript/core/beacons.d.ts +32 -0
  40. package/lib/typescript/core/cache.d.ts +53 -0
  41. package/lib/typescript/core/click.d.ts +8 -0
  42. package/lib/typescript/core/client.d.ts +58 -0
  43. package/lib/typescript/core/config.d.ts +24 -0
  44. package/lib/typescript/core/http.d.ts +34 -0
  45. package/lib/typescript/core/index.d.ts +8 -0
  46. package/lib/typescript/core/outbox.d.ts +56 -0
  47. package/lib/typescript/core/tracker.d.ts +95 -0
  48. package/lib/typescript/core/types.d.ts +170 -0
  49. package/lib/typescript/index.d.ts +3 -0
  50. package/lib/typescript/interstitial.d.ts +2 -0
  51. package/lib/typescript/react/EthiclyInterstitial.d.ts +39 -0
  52. package/lib/typescript/react/useEthiclyInterstitial.d.ts +20 -0
  53. package/lib/typescript/version.d.ts +2 -0
  54. package/package.json +101 -4
  55. package/src/core/adapters.ts +337 -0
  56. package/src/core/beacons.ts +81 -0
  57. package/src/core/cache.ts +216 -0
  58. package/src/core/click.ts +16 -0
  59. package/src/core/client.ts +547 -0
  60. package/src/core/config.ts +111 -0
  61. package/src/core/http.ts +115 -0
  62. package/src/core/index.ts +14 -0
  63. package/src/core/outbox.ts +193 -0
  64. package/src/core/tracker.ts +371 -0
  65. package/src/core/types.ts +180 -0
  66. package/src/index.ts +5 -0
  67. package/src/interstitial.ts +4 -0
  68. package/src/react/EthiclyInterstitial.tsx +386 -0
  69. package/src/react/useEthiclyInterstitial.ts +74 -0
  70. package/src/version.ts +2 -0
@@ -0,0 +1,337 @@
1
+ // Default in-memory adapters and helpers that wrap the usual Expo modules.
2
+ // Nothing here imports a native module: the app passes the module in.
3
+
4
+ import type { FileCacheAdapter, KeyValueStorage, Logger } from './types';
5
+
6
+ /** In-memory key-value store. Lost when the process ends. */
7
+ export function createMemoryStorage(): KeyValueStorage & { data: Map<string, string> } {
8
+ const data = new Map<string, string>();
9
+ return {
10
+ data,
11
+ async getItem(k) { return data.has(k) ? (data.get(k) as string) : null; },
12
+ async setItem(k, v) { data.set(k, v); },
13
+ async removeItem(k) { data.delete(k); },
14
+ };
15
+ }
16
+
17
+ /**
18
+ * In-memory "cache" that downloads nothing: the uri it returns is the remote
19
+ * URL, so the player streams. The default when no fileCache is given.
20
+ */
21
+ export function createMemoryFileCache(): FileCacheAdapter {
22
+ const files = new Set<string>();
23
+ return {
24
+ async download(url) { files.add(url); return { uri: url, bytes: 0 }; },
25
+ async exists(uri) { return files.has(uri); },
26
+ async delete(uri) { files.delete(uri); },
27
+ async size() { return 0; },
28
+ async list() { return Array.from(files); },
29
+ };
30
+ }
31
+
32
+ /** The legacy expo-file-system API (SDK 50 to 53, or `expo-file-system/legacy` on 54+). */
33
+ export interface ExpoFileSystemLike {
34
+ cacheDirectory: string | null;
35
+ downloadAsync(url: string, fileUri: string): Promise<{ uri: string; status: number }>;
36
+ // md5 is listed so expo-file-system 19+'s InfoOptions (md5 only; size is always returned) still matches.
37
+ getInfoAsync(fileUri: string, options?: { md5?: boolean; size?: boolean }): Promise<{ exists: boolean; size?: number }>;
38
+ deleteAsync(fileUri: string, options?: { idempotent?: boolean }): Promise<void>;
39
+ makeDirectoryAsync(fileUri: string, options?: { intermediates?: boolean }): Promise<void>;
40
+ readDirectoryAsync?(fileUri: string): Promise<string[]>;
41
+ createDownloadResumable?(
42
+ url: string,
43
+ fileUri: string,
44
+ options?: Record<string, unknown>,
45
+ callback?: (p: { totalBytesWritten: number; totalBytesExpectedToWrite: number }) => void,
46
+ ): {
47
+ downloadAsync(): Promise<{ uri: string; status: number } | undefined>;
48
+ cancelAsync?(): Promise<void>;
49
+ pauseAsync(): Promise<unknown>;
50
+ };
51
+ }
52
+
53
+ /** A file or directory of the object API (`File`, `Directory`) of expo-file-system 19+ (Expo SDK 54+). */
54
+ export interface ExpoFsEntryLike {
55
+ readonly uri: string;
56
+ readonly name?: string;
57
+ readonly exists: boolean;
58
+ delete(): void;
59
+ }
60
+ export interface ExpoFsFileLike extends ExpoFsEntryLike { readonly size: number | null }
61
+ export interface ExpoFsDirectoryLike extends ExpoFsEntryLike {
62
+ create(options?: { intermediates?: boolean; idempotent?: boolean }): void;
63
+ list(): ExpoFsEntryLike[];
64
+ }
65
+
66
+ /**
67
+ * The object API that `expo-file-system` exports from Expo SDK 54 on. Its root
68
+ * export still has functions named like the legacy ones, but they throw at
69
+ * runtime, so this shape is checked first.
70
+ */
71
+ export interface ExpoFileSystemModernLike {
72
+ File: {
73
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
74
+ new (...uris: any[]): ExpoFsFileLike;
75
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
76
+ downloadFileAsync(url: string, destination: any, options?: { idempotent?: boolean }): Promise<unknown>;
77
+ /** Newer versions: a download with progress and cancel. */
78
+ createDownloadTask?(
79
+ url: string,
80
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
81
+ destination: any,
82
+ options?: { onProgress?: (p: { bytesWritten: number; totalBytes: number }) => void },
83
+ ): { downloadAsync(): Promise<unknown>; cancel(): void };
84
+ };
85
+ Directory: {
86
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
87
+ new (...uris: any[]): ExpoFsDirectoryLike;
88
+ };
89
+ Paths: { readonly cache: { readonly uri: string } };
90
+ }
91
+
92
+ /**
93
+ * Creative cache on disk via expo-file-system. Pass the module as your app
94
+ * imports it, on any Expo SDK from 50; the adapter works out which API it has:
95
+ * import * as FileSystem from 'expo-file-system'; // or 'expo-file-system/legacy'
96
+ * createEthicly({ ..., fileCache: createExpoFileCache(FileSystem) })
97
+ */
98
+ export const DEFAULT_CACHE_SUBDIRECTORY = 'ethicly-ads/';
99
+
100
+ /**
101
+ * The cache sweep deletes every file in this directory that the SDK's index
102
+ * does not list, so it must be a folder of its own: one plain name directly
103
+ * under the app's cache directory. An empty, nested or traversing name ('',
104
+ * '/', '..', 'a/b') would point the sweep at the host app's files, so anything
105
+ * else falls back to the default rather than risk deleting them.
106
+ */
107
+ export function safeCacheSubdirectory(subdirectory: unknown): string {
108
+ if (typeof subdirectory !== 'string') return DEFAULT_CACHE_SUBDIRECTORY;
109
+ const name = subdirectory.trim().replace(/\/+$/, '');
110
+ if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(name) || name === '.' || name.includes('..')) {
111
+ return DEFAULT_CACHE_SUBDIRECTORY;
112
+ }
113
+ return `${name}/`;
114
+ }
115
+
116
+ function isModernFs(fs: unknown): fs is ExpoFileSystemModernLike {
117
+ const m = fs as Partial<ExpoFileSystemModernLike> | null;
118
+ return !!m && typeof m.File === 'function' && typeof m.Directory === 'function'
119
+ && typeof m.File.downloadFileAsync === 'function' && !!m.Paths;
120
+ }
121
+
122
+ function isLegacyFs(fs: unknown): fs is ExpoFileSystemLike {
123
+ const l = fs as Partial<ExpoFileSystemLike> | null;
124
+ return !!l && typeof l.cacheDirectory === 'string' && !!l.cacheDirectory
125
+ && typeof l.downloadAsync === 'function' && typeof l.getInfoAsync === 'function'
126
+ && typeof l.deleteAsync === 'function' && typeof l.makeDirectoryAsync === 'function';
127
+ }
128
+
129
+ /**
130
+ * A file cache over either expo-file-system API: the object API of SDK 54+
131
+ * (`File`, `Directory`, `Paths`), else the legacy functions (`getInfoAsync`,
132
+ * `downloadAsync`, ...). Anything else gets the streaming cache, which writes
133
+ * nothing to disk, and one warning through `logger` (default `console`).
134
+ */
135
+ export function createExpoFileCache(
136
+ fs: ExpoFileSystemLike | ExpoFileSystemModernLike,
137
+ subdirectory: string = DEFAULT_CACHE_SUBDIRECTORY,
138
+ logger?: Logger,
139
+ ): FileCacheAdapter {
140
+ const sub = safeCacheSubdirectory(subdirectory);
141
+ if (isModernFs(fs)) return modernFileCache(fs, sub);
142
+ if (isLegacyFs(fs)) return legacyFileCache(fs, sub);
143
+ safeLogger(logger || consoleLogger()).warn(
144
+ 'createExpoFileCache: not an expo-file-system module (no File/Directory/Paths, no cacheDirectory); creatives will stream',
145
+ );
146
+ return createMemoryFileCache();
147
+ }
148
+
149
+ function consoleLogger(): Logger {
150
+ const c = (globalThis as { console?: Logger }).console;
151
+ return { warn: (m, ...rest) => c?.warn?.(m, ...rest), error: (m, ...rest) => c?.error?.(m, ...rest) };
152
+ }
153
+
154
+ function legacyFileCache(fs: ExpoFileSystemLike, sub: string): FileCacheAdapter {
155
+ const dir = `${fs.cacheDirectory}${sub}`;
156
+ let made: Promise<void> | null = null;
157
+ const sizeOf = async (uri: string): Promise<number> => {
158
+ const info = await fs.getInfoAsync(uri, { size: true });
159
+ return info.exists && typeof info.size === 'number' ? info.size : 0;
160
+ };
161
+ return {
162
+ async download(url, fileName, opts) {
163
+ if (!made) made = fs.makeDirectoryAsync(dir, { intermediates: true }).catch(() => undefined);
164
+ await made;
165
+ const target = dir + fileName;
166
+ const max = opts?.maxBytes;
167
+ let res: { uri: string; status: number } | undefined;
168
+ let tooBig = false;
169
+ if (max !== undefined && fs.createDownloadResumable) {
170
+ // Stop as soon as the server announces, or we have written, more than the budget.
171
+ const dl = fs.createDownloadResumable(url, target, {}, (p) => {
172
+ if (tooBig) return;
173
+ if (p.totalBytesExpectedToWrite > max || p.totalBytesWritten > max) {
174
+ tooBig = true;
175
+ void (dl.cancelAsync ? dl.cancelAsync() : dl.pauseAsync()).catch(() => undefined);
176
+ }
177
+ });
178
+ res = await dl.downloadAsync().catch(() => undefined);
179
+ } else {
180
+ res = await fs.downloadAsync(url, target);
181
+ }
182
+ if (tooBig || !res || res.status < 200 || res.status >= 300) {
183
+ await fs.deleteAsync(target, { idempotent: true }).catch(() => undefined);
184
+ throw new Error(tooBig ? 'creative over the cache budget' : `download failed (${res ? res.status : 'cancelled'})`);
185
+ }
186
+ return { uri: res.uri, bytes: await sizeOf(res.uri) };
187
+ },
188
+ async exists(uri) { return (await fs.getInfoAsync(uri)).exists; },
189
+ async delete(uri) { await fs.deleteAsync(uri, { idempotent: true }); },
190
+ size: sizeOf,
191
+ uriFor: (fileName) => dir + fileName,
192
+ async list() {
193
+ if (!fs.readDirectoryAsync) return [];
194
+ const names = await fs.readDirectoryAsync(dir).catch(() => [] as string[]);
195
+ return names.map((n) => dir + n);
196
+ },
197
+ };
198
+ }
199
+
200
+ /**
201
+ * The same cache over the object API. Its calls are synchronous and throw on
202
+ * failure; every adapter method is async, so a throw becomes a rejection and
203
+ * never reaches the host. Files are addressed by uri strings built from the
204
+ * cache directory's uri, so the index and the sweep compare like with like.
205
+ */
206
+ function modernFileCache(fs: ExpoFileSystemModernLike, sub: string): FileCacheAdapter {
207
+ let dirUri: string | null = null;
208
+ const dir = (): string => {
209
+ if (dirUri === null) {
210
+ const cache = fs.Paths.cache.uri;
211
+ dirUri = `${cache.endsWith('/') ? cache : `${cache}/`}${sub}`;
212
+ }
213
+ return dirUri;
214
+ };
215
+ const file = (uri: string) => new fs.File(uri);
216
+ const remove = (uri: string) => {
217
+ const f = file(uri);
218
+ if (f.exists) f.delete();
219
+ };
220
+ const sizeOf = async (uri: string): Promise<number> => {
221
+ const f = file(uri);
222
+ return f.exists && typeof f.size === 'number' && f.size > 0 ? f.size : 0;
223
+ };
224
+ let made = false;
225
+ return {
226
+ async download(url, fileName, opts) {
227
+ if (!made) {
228
+ const d = new fs.Directory(dir());
229
+ if (!d.exists) d.create({ intermediates: true, idempotent: true });
230
+ made = true;
231
+ }
232
+ const target = dir() + fileName;
233
+ const max = opts?.maxBytes;
234
+ let tooBig = false;
235
+ try {
236
+ remove(target);
237
+ const createTask = fs.File.createDownloadTask;
238
+ if (max !== undefined && typeof createTask === 'function') {
239
+ // Stop as soon as the server announces, or we have written, more than the budget.
240
+ const task = createTask.call(fs.File, url, file(target), {
241
+ onProgress: (p) => {
242
+ if (tooBig || !(p.totalBytes > max || p.bytesWritten > max)) return;
243
+ tooBig = true;
244
+ try { task.cancel(); } catch { /* already settled */ }
245
+ },
246
+ });
247
+ await task.downloadAsync();
248
+ } else {
249
+ await fs.File.downloadFileAsync(url, file(target), { idempotent: true });
250
+ }
251
+ } catch (e) {
252
+ try { remove(target); } catch { /* nothing to remove */ }
253
+ throw tooBig ? new Error('creative over the cache budget') : e;
254
+ }
255
+ // Without a progress callback the whole file lands first: check it now
256
+ // and delete it if it is over the budget.
257
+ const bytes = await sizeOf(target);
258
+ if (tooBig || (max !== undefined && bytes > max)) {
259
+ try { remove(target); } catch { /* ignore */ }
260
+ throw new Error('creative over the cache budget');
261
+ }
262
+ return { uri: target, bytes };
263
+ },
264
+ async exists(uri) { return file(uri).exists; },
265
+ async delete(uri) { remove(uri); },
266
+ size: sizeOf,
267
+ uriFor: (fileName) => dir() + fileName,
268
+ async list() {
269
+ const d = new fs.Directory(dir());
270
+ if (!d.exists) return [];
271
+ // Files only: the SDK never creates folders here, so it never deletes one.
272
+ return d.list()
273
+ .filter((e) => e instanceof fs.File)
274
+ .map((e) => e.name || e.uri.replace(/\/+$/, '').split('/').pop() || '')
275
+ .filter((n) => n && n !== '.' && n !== '..' && !n.includes('/'))
276
+ .map((n) => dir() + n);
277
+ },
278
+ };
279
+ }
280
+
281
+ // Metro defines __DEV__ in every React Native bundle: true in development,
282
+ // false in a release build. Node, jest and other runtimes may not define it.
283
+ declare const __DEV__: boolean | undefined;
284
+
285
+ /**
286
+ * True only in a React Native release build (`__DEV__ === false`). Where
287
+ * `__DEV__` is not defined at all the code is not running from a Metro bundle
288
+ * (a Node script such as scripts/live-test.mjs, or tests), which is never a
289
+ * shipped app, so that counts as not release.
290
+ */
291
+ export function isReleaseBuild(): boolean {
292
+ return typeof __DEV__ !== 'undefined' && __DEV__ === false;
293
+ }
294
+
295
+ /** The part of React Native's AppState the client uses for sessions. */
296
+ export interface AppStateLike {
297
+ currentState?: string | null;
298
+ addEventListener(type: 'change', listener: (state: string) => void): { remove(): void } | undefined | void;
299
+ }
300
+
301
+ /**
302
+ * React Native's AppState, or null outside React Native. The core takes no
303
+ * hard dependency on react-native: a require inside try/catch is an optional
304
+ * dependency for Metro (the React Native and Expo Metro configs both set
305
+ * allowOptionalDependencies), and in Node it simply fails and returns null.
306
+ */
307
+ export function defaultAppState(): AppStateLike | null {
308
+ try {
309
+ // @ts-ignore: the build compiles without Node's types, where require is undeclared.
310
+ const rn = typeof require === 'function' ? require('react-native') : null;
311
+ const s = rn && (rn as { AppState?: AppStateLike }).AppState;
312
+ return s && typeof s.addEventListener === 'function' ? s : null;
313
+ } catch {
314
+ return null;
315
+ }
316
+ }
317
+
318
+ /** Wrap a logger so a throwing logger can never reach the host app. */
319
+ export function safeLogger(logger: Logger | undefined): Required<Logger> {
320
+ const call = (level: keyof Logger) => (message: string, ...rest: unknown[]) => {
321
+ try { logger?.[level]?.(`[ethicly] ${message}`, ...rest); } catch { /* never throw */ }
322
+ };
323
+ return { debug: call('debug'), info: call('info'), warn: call('warn'), error: call('error') };
324
+ }
325
+
326
+ /** UUID v4. Uses the platform RNG when there is one (Hermes has none by default). */
327
+ export function uuidv4(): string {
328
+ const c = (globalThis as { crypto?: { randomUUID?: () => string; getRandomValues?: (a: Uint8Array) => Uint8Array } }).crypto;
329
+ if (c && typeof c.randomUUID === 'function') return c.randomUUID();
330
+ const b = new Uint8Array(16);
331
+ if (c && typeof c.getRandomValues === 'function') c.getRandomValues(b);
332
+ else for (let i = 0; i < 16; i++) b[i] = Math.floor(Math.random() * 256);
333
+ b[6] = (b[6] & 0x0f) | 0x40;
334
+ b[8] = (b[8] & 0x3f) | 0x80;
335
+ const h = Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
336
+ return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
337
+ }
@@ -0,0 +1,81 @@
1
+ // Beacon delivery with the retry rules of doc "Rules that hold for every
2
+ // route": retry timeouts and 5xx with backoff, wait Retry-After on 429, never
3
+ // retry any other 4xx (422 included). /click never comes through here.
4
+
5
+ import { httpRequest, sleep, type HttpResult, type RouteGate } from './http';
6
+ import type { FetchLike, Logger } from './types';
7
+
8
+ export type BeaconRoute = 'impression' | 'viewable' | 'video-event';
9
+
10
+ export interface BeaconContext {
11
+ fetch: FetchLike;
12
+ serveBase(): string;
13
+ headers(): Record<string, string>;
14
+ gate: RouteGate;
15
+ now(): number;
16
+ log: Required<Logger>;
17
+ }
18
+
19
+ export const BEACON_TIMEOUT_MS = 10000;
20
+ export const ONE_HOUR_MS = 3600 * 1000;
21
+
22
+ /** The backoff ceiling for a retry: 1 s doubling per attempt, capped at 60 s. */
23
+ export function backoffCapMs(attempt: number): number {
24
+ return Math.min(60000, 1000 * 2 ** Math.max(0, attempt - 1));
25
+ }
26
+
27
+ /**
28
+ * Full jitter: a uniformly random wait between 0 and the ceiling, so installs
29
+ * that failed together (one outage, one carrier NAT) do not retry together.
30
+ */
31
+ export function backoffMs(attempt: number, random: () => number = Math.random): number {
32
+ const r = random();
33
+ return Math.floor(backoffCapMs(attempt) * (r >= 0 && r < 1 ? r : 0.5));
34
+ }
35
+
36
+ /**
37
+ * Send one beacon, retrying timeouts, network errors and 5xx with backoff
38
+ * (full jitter under a ceiling of 1 s doubling, capped at 60 s) and 429
39
+ * after Retry-After, until the deadline (doc lifecycle rule 7: give up after
40
+ * one hour). Resolves with the last answer, or null when the deadline passed
41
+ * before it could be sent.
42
+ * `maxAttempts` is unlimited unless given. Never throws.
43
+ */
44
+ export async function sendWithRetry(
45
+ ctx: BeaconContext,
46
+ route: BeaconRoute,
47
+ body: unknown,
48
+ opts: { deadline: number; maxAttempts?: number },
49
+ ): Promise<HttpResult | null> {
50
+ const max = opts.maxAttempts ?? Infinity;
51
+ let last: HttpResult | null = null;
52
+ for (let attempt = 1; attempt <= max; attempt++) {
53
+ const wait = ctx.gate.waitMs(route);
54
+ if (wait > 0) {
55
+ if (ctx.now() + wait > opts.deadline) return last;
56
+ await sleep(wait);
57
+ }
58
+ if (ctx.now() > opts.deadline) return last;
59
+ last = await httpRequest(ctx.fetch, `${ctx.serveBase()}/${route}`, {
60
+ method: 'POST',
61
+ headers: ctx.headers(),
62
+ body,
63
+ timeoutMs: BEACON_TIMEOUT_MS,
64
+ });
65
+ if (last.status === 429) {
66
+ ctx.gate.block(route, last.retryAfterS);
67
+ ctx.log.warn(`/${route} rate limited, retry after ${last.retryAfterS ?? 1}s`);
68
+ continue;
69
+ }
70
+ if (last.status === 0 || last.status >= 500) {
71
+ const b = backoffMs(attempt);
72
+ ctx.log.debug(`/${route} ${last.status === 0 ? 'timed out or failed' : `answered ${last.status}`}, attempt ${attempt}`);
73
+ if (attempt >= max || ctx.now() + b > opts.deadline) return last;
74
+ await sleep(b);
75
+ continue;
76
+ }
77
+ if (last.status >= 400) ctx.log.warn(`/${route} answered ${last.status}, not retried`, last.body);
78
+ return last;
79
+ }
80
+ return last;
81
+ }
@@ -0,0 +1,216 @@
1
+ // Creative cache: downloads the video and poster of a served ad (doc
2
+ // "Lifecycle and timing" step 3) within prefetch.max_cache_mb and
3
+ // prefetch.max_cached_creatives, evicting least recently used first.
4
+ //
5
+ // Disk use stays bounded even if the app dies mid-download or the index is
6
+ // lost (for example with the default in-memory storage):
7
+ // - a file's size is checked before it is written (HEAD Content-Length, and
8
+ // the adapter aborts a download that grows past the remaining budget);
9
+ // - the index records each file name as pending BEFORE its download starts,
10
+ // and is written again as soon as the download lands;
11
+ // - on first use every pending file, and every file in the SDK's cache
12
+ // directory that the index does not list, is deleted.
13
+
14
+ import type { FileCacheAdapter, KeyValueStorage, Logger } from './types';
15
+
16
+ interface CachedFile { url: string; uri: string; bytes: number }
17
+ interface Entry { key: string; files: CachedFile[]; lastUsed: number }
18
+ interface Index { entries: Entry[]; pending?: string[] }
19
+
20
+ export interface CacheLimits { maxCreatives: number; maxBytes: number }
21
+
22
+ export interface CachedMedia {
23
+ /** remote URL -> local uri, for the files that are cached. */
24
+ uris: Record<string, string>;
25
+ }
26
+
27
+ /** Content-Length of a URL, or null when unknown. */
28
+ export type SizeProbe = (url: string) => Promise<number | null>;
29
+
30
+ function hash(s: string): string {
31
+ let h = 5381;
32
+ for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
33
+ return h.toString(36);
34
+ }
35
+
36
+ function extOf(url: string, fallback: string): string {
37
+ const m = /\.([a-z0-9]{2,5})(?:[?#]|$)/i.exec(url);
38
+ return m ? m[1].toLowerCase() : fallback;
39
+ }
40
+
41
+ function baseName(uri: string): string {
42
+ return uri.replace(/[?#].*$/, '').split('/').pop() || uri;
43
+ }
44
+
45
+ export class CreativeCache {
46
+ private entries: Entry[] = [];
47
+ /** File names whose download has started but not landed. */
48
+ private pending: string[] = [];
49
+ private loaded: Promise<void> | null = null;
50
+ private chain: Promise<unknown> = Promise.resolve();
51
+
52
+ constructor(
53
+ private files: FileCacheAdapter,
54
+ private storage: KeyValueStorage,
55
+ private storageKey: string,
56
+ private now: () => number,
57
+ private log: Required<Logger>,
58
+ private probeSize: SizeProbe = async () => null,
59
+ ) {}
60
+
61
+ private load(): Promise<void> {
62
+ if (!this.loaded) this.loaded = this.loadNow();
63
+ return this.loaded;
64
+ }
65
+
66
+ private async loadNow(): Promise<void> {
67
+ let pending: string[] = [];
68
+ try {
69
+ const raw = await this.storage.getItem(this.storageKey);
70
+ const parsed = raw ? JSON.parse(raw) : null;
71
+ if (Array.isArray(parsed)) this.entries = parsed as Entry[]; // 0.1.0 pre-release shape
72
+ else if (parsed && Array.isArray(parsed.entries)) {
73
+ this.entries = (parsed as Index).entries;
74
+ pending = Array.isArray(parsed.pending) ? (parsed as Index).pending! : [];
75
+ }
76
+ } catch {
77
+ this.entries = [];
78
+ }
79
+ await this.sweep(pending);
80
+ }
81
+
82
+ /**
83
+ * Delete the downloads a previous run left unfinished, and every file in the
84
+ * cache directory that the index does not list.
85
+ */
86
+ private async sweep(pending: string[]): Promise<void> {
87
+ const known = new Set<string>();
88
+ for (const e of this.entries) for (const f of e.files) known.add(baseName(f.uri));
89
+ // The directory listing below covers these too; this also works for an
90
+ // adapter that cannot list its directory.
91
+ if (this.files.uriFor) {
92
+ for (const name of pending) {
93
+ if (!known.has(name)) await this.files.delete(this.files.uriFor(name)).catch(() => undefined);
94
+ }
95
+ }
96
+ let listed: string[] = [];
97
+ try {
98
+ listed = this.files.list ? await this.files.list() : [];
99
+ } catch (e) {
100
+ this.log.warn('could not list the creative cache', e);
101
+ }
102
+ for (const uri of listed) {
103
+ if (!known.has(baseName(uri))) {
104
+ await this.files.delete(uri).catch(() => undefined);
105
+ this.log.debug(`swept unindexed file ${baseName(uri)}`);
106
+ }
107
+ }
108
+ await this.persist();
109
+ }
110
+
111
+ private persist(): Promise<void> {
112
+ const index: Index = { entries: this.entries, pending: this.pending };
113
+ return this.storage.setItem(this.storageKey, JSON.stringify(index)).catch(() => undefined);
114
+ }
115
+
116
+ /** Number of cached creatives and their total size, for tests and debugging. */
117
+ async stats(): Promise<{ creatives: number; bytes: number; keys: string[] }> {
118
+ await this.load();
119
+ return {
120
+ creatives: this.entries.length,
121
+ bytes: this.entries.reduce((n, e) => n + this.size(e), 0),
122
+ keys: this.entries.map((e) => e.key),
123
+ };
124
+ }
125
+
126
+ /**
127
+ * Make sure the files of one creative are on disk. Never throws: a file that
128
+ * cannot be cached is simply left out of the result and streamed instead.
129
+ * `allowed()` is checked before every download so setAdsEnabled(false)
130
+ * stops a download that has not started yet.
131
+ */
132
+ ensure(adId: number, urls: string[], limits: CacheLimits, allowed: () => boolean): Promise<CachedMedia> {
133
+ const run = this.chain.then(() => this.ensureNow(adId, urls, limits, allowed));
134
+ this.chain = run.catch(() => undefined);
135
+ return run;
136
+ }
137
+
138
+ private async ensureNow(adId: number, urls: string[], limits: CacheLimits, allowed: () => boolean): Promise<CachedMedia> {
139
+ await this.load();
140
+ if (limits.maxCreatives <= 0 || limits.maxBytes <= 0) return { uris: {} };
141
+ const key = `${adId}:${hash(urls.join('|'))}`;
142
+
143
+ let entry = this.entries.find((e) => e.key === key);
144
+ if (entry) {
145
+ const present = await Promise.all(entry.files.map((f) => this.files.exists(f.uri).catch(() => false)));
146
+ entry.files = entry.files.filter((_, i) => present[i]);
147
+ } else {
148
+ entry = { key, files: [], lastUsed: 0 };
149
+ this.entries.push(entry);
150
+ }
151
+ entry.lastUsed = this.now();
152
+
153
+ for (const url of urls) {
154
+ if (entry.files.some((f) => f.url === url)) continue;
155
+ if (!allowed()) break;
156
+ // One creative may use the whole budget (older ones are evicted), never more.
157
+ const budget = limits.maxBytes - this.size(entry);
158
+ const known = await this.probeSize(url).catch(() => null);
159
+ if (known !== null && known > budget) {
160
+ this.log.info(`${url} is ${known} bytes, over the cache budget: it will stream`);
161
+ continue;
162
+ }
163
+ // Known size: make room first, so the disk never holds more than the budget.
164
+ if (known !== null) await this.evict(limits, entry, known);
165
+ const name = `ethicly-${adId}-${hash(url)}.${extOf(url, 'bin')}`;
166
+ this.pending = [name];
167
+ await this.persist();
168
+ try {
169
+ const res = await this.files.download(url, name, { maxBytes: budget });
170
+ const bytes = typeof res.bytes === 'number' && res.bytes > 0 ? res.bytes : await this.files.size(res.uri).catch(() => 0);
171
+ if (bytes > budget) {
172
+ await this.files.delete(res.uri).catch(() => undefined);
173
+ this.log.info(`${url} is over the cache budget: it will stream`);
174
+ } else {
175
+ entry.files.push({ url, uri: res.uri, bytes });
176
+ }
177
+ } catch (e) {
178
+ this.log.warn(`could not cache ${url}, it will stream`, e);
179
+ }
180
+ this.pending = [];
181
+ // Persist right after each file lands, so the index never lags the disk
182
+ // by more than the download in flight (which the sweep covers).
183
+ await this.evict(limits, entry);
184
+ await this.persist();
185
+ }
186
+
187
+ if (entry.files.length === 0) this.entries = this.entries.filter((e) => e !== entry);
188
+ await this.evict(limits, entry);
189
+ await this.persist();
190
+
191
+ const uris: Record<string, string> = {};
192
+ for (const f of this.entries.includes(entry) ? entry.files : []) uris[f.url] = f.uri;
193
+ return { uris };
194
+ }
195
+
196
+ private size(e: Entry): number {
197
+ return e.files.reduce((n, f) => n + f.bytes, 0);
198
+ }
199
+
200
+ /**
201
+ * LRU eviction, leaving room for `incoming` more bytes. The current entry
202
+ * goes last, and only if it alone is too big.
203
+ */
204
+ private async evict(limits: CacheLimits, current: Entry, incoming = 0): Promise<void> {
205
+ const total = () => this.entries.reduce((n, e) => n + this.size(e), 0) + incoming;
206
+ const victims = () => this.entries.filter((e) => e !== current).sort((a, b) => a.lastUsed - b.lastUsed);
207
+ while (this.entries.length > limits.maxCreatives || total() > limits.maxBytes) {
208
+ if (incoming > 0 && victims().length === 0) break;
209
+ const v = victims()[0] || (this.entries.includes(current) ? current : undefined);
210
+ if (!v) break;
211
+ this.entries = this.entries.filter((e) => e !== v);
212
+ for (const f of v.files) await this.files.delete(f.uri).catch(() => undefined);
213
+ this.log.debug(`evicted creative ${v.key}`);
214
+ }
215
+ }
216
+ }
@@ -0,0 +1,16 @@
1
+ // Doc "Click handling" step 3, the same rule as trackClickAndNavigate in
2
+ // frontend/public/ethicly.js.
3
+
4
+ /**
5
+ * Append ethicly_click=<token> to the destination. The separator is "&" when
6
+ * the URL already contains a "?" anywhere, otherwise "?". The token is
7
+ * percent-encoded and nothing else in the URL changes.
8
+ */
9
+ export function appendClickToken(destinationUrl: string, clickToken: string | null | undefined): string {
10
+ if (typeof clickToken !== 'string' || clickToken === '') return destinationUrl;
11
+ const sep = destinationUrl.indexOf('?') >= 0 ? '&' : '?';
12
+ return `${destinationUrl}${sep}ethicly_click=${encodeURIComponent(clickToken)}`;
13
+ }
14
+
15
+ /** The /click budget: the website snippet aborts at exactly 500 ms. */
16
+ export const CLICK_TIMEOUT_MS = 500;