castle-web-sdk 0.4.1 → 0.4.3

package/dist/storage.js

@@ -0,0 +1,405 @@
+import { getAuth, requireAuthToken } from "./auth";
+import { getDeckContext, requireDeckId } from "./context";
+import { CastleError } from "./errors";
+import { graphqlRequest } from "./graphql";
+const FLUSH_INTERVAL_MS = 2000;
+class PrivateStorageImpl {
+    cache = new Map();
+    dirty = new Map();
+    loadPromise = null;
+    loadedContextKey = null;
+    flushTimer = null;
+    async get(key) {
+        await this.ensureLoaded("Storage.get");
+        return (this.cache.get(key) ?? null);
+    }
+    set(key, value) {
+        const encoded = encodeStorageValue(value, "Storage.set");
+        this.cache.set(key, value);
+        this.dirty.set(key, encoded);
+        this.scheduleFlush();
+    }
+    remove(key) {
+        this.cache.delete(key);
+        this.dirty.set(key, null);
+        this.scheduleFlush();
+    }
+    async flush() {
+        if (this.dirty.size === 0)
+            return;
+        const context = await currentContext("Storage.flush");
+        const snapshot = new Map(this.dirty);
+        const data = await storageGraphql(UPDATE_DECK_STORAGE_MUTATION, {
+            deckId: context.deckId,
+            sessionId: context.sessionId,
+            updates: updatesFromDirty(snapshot),
+        }, "updateDeckStorage");
+        this.applyServerBlob(data.updateDeckStorage, contextKey(context.deckId, context.sessionId));
+        clearAcknowledgedDirty(this.dirty, snapshot);
+        this.overlayDirty();
+    }
+    ensureLoaded(operation) {
+        if (!this.loadPromise) {
+            this.loadPromise = this.load(operation).catch((error) => {
+                this.loadPromise = null;
+                throw error;
+            });
+        }
+        return this.loadPromise;
+    }
+    async load(operation) {
+        const context = await currentContext(operation);
+        const key = contextKey(context.deckId, context.sessionId);
+        if (this.loadedContextKey === key)
+            return;
+        const data = await storageGraphql(DECK_STORAGE_QUERY, { deckId: context.deckId, sessionId: context.sessionId }, "deckStorage");
+        this.cache = decodeStorageBlob(data.deckStorage, operation);
+        this.loadedContextKey = key;
+        this.overlayDirty();
+    }
+    applyServerBlob(blob, loadedContextKey) {
+        this.cache = decodeStorageBlob(blob, "Storage.flush");
+        this.loadedContextKey = loadedContextKey;
+    }
+    overlayDirty() {
+        for (const [key, encoded] of this.dirty) {
+            if (encoded === null) {
+                this.cache.delete(key);
+            }
+            else {
+                this.cache.set(key, decodeStorageValue(encoded, "Storage.dirty"));
+            }
+        }
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flush();
+        }, FLUSH_INTERVAL_MS);
+    }
+}
+class SharedStorageImpl {
+    dirtyBuckets = new Map();
+    buckets = new Map();
+    readBatches = new Map();
+    pendingWrites = new Set();
+    pendingWriteErrors = [];
+    flushTimer = null;
+    async get(scope, userOrKey, maybeKey) {
+        const bucket = await readBucket(scope, userOrKey, maybeKey, "SharedStorage.get");
+        const key = maybeKey ?? userOrKey;
+        await this.awaitPendingWrites("SharedStorage.get");
+        const dirty = this.peekDirty(bucket, key);
+        if (dirty !== undefined) {
+            return (dirty === null ? null : decodeStorageValue(dirty, "SharedStorage.get"));
+        }
+        return this.queueRead(bucket, key);
+    }
+    set(scope, key, value) {
+        this.enqueueWrite(scope, key, encodeStorageValue(value, "SharedStorage.set"), "SharedStorage.set");
+    }
+    remove(scope, key) {
+        this.enqueueWrite(scope, key, null, "SharedStorage.remove");
+    }
+    async flush() {
+        await this.awaitPendingWrites("SharedStorage.flush");
+        if (this.dirtyBuckets.size === 0)
+            return;
+        const tasks = Array.from(this.dirtyBuckets, ([bucketKey, dirty]) => this.flushBucket(bucketKey, new Map(dirty)));
+        await Promise.all(tasks);
+    }
+    async write(scope, key, encoded, operation) {
+        const bucket = await writeBucket(scope, operation);
+        const bucketKey = makeBucketKey(bucket);
+        this.buckets.set(bucketKey, bucket);
+        const dirty = this.dirtyBuckets.get(bucketKey) ?? new Map();
+        dirty.set(key, encoded);
+        this.dirtyBuckets.set(bucketKey, dirty);
+        this.scheduleFlush();
+    }
+    enqueueWrite(scope, key, encoded, operation) {
+        const pending = this.write(scope, key, encoded, operation)
+            .catch((error) => {
+            this.pendingWriteErrors.push(error);
+        })
+            .finally(() => {
+            this.pendingWrites.delete(pending);
+        });
+        this.pendingWrites.add(pending);
+    }
+    async awaitPendingWrites(operation) {
+        if (this.pendingWrites.size > 0) {
+            await Promise.all(this.pendingWrites);
+        }
+        const error = this.pendingWriteErrors.shift();
+        if (error instanceof Error)
+            throw error;
+        if (error) {
+            throw storageError("CASTLE_STORAGE_WRITE_FAILED", "Queued shared storage write failed.", operation);
+        }
+    }
+    async queueRead(bucket, key) {
+        const bucketKey = makeBucketKey(bucket);
+        let batch = this.readBatches.get(bucketKey);
+        if (!batch) {
+            batch = { bucket, reads: new Map(), scheduled: false };
+            this.readBatches.set(bucketKey, batch);
+        }
+        const reads = batch.reads.get(key) ?? [];
+        batch.reads.set(key, reads);
+        const promise = new Promise((resolve, reject) => {
+            reads.push({ resolve, reject });
+        });
+        if (!batch.scheduled) {
+            batch.scheduled = true;
+            queueMicrotask(() => {
+                void this.flushReadBatch(bucketKey);
+            });
+        }
+        return (await promise);
+    }
+    async flushReadBatch(bucketKey) {
+        const batch = this.readBatches.get(bucketKey);
+        if (!batch)
+            return;
+        this.readBatches.delete(bucketKey);
+        const keys = Array.from(batch.reads.keys());
+        try {
+            const context = await currentContext("SharedStorage.get");
+            const data = await storageGraphql(SHARED_DECK_STORAGE_QUERY, sharedVariables(context.deckId, batch.bucket, { keys }), "sharedDeckStorage");
+            this.resolveReadBatch(batch, data.sharedDeckStorage);
+        }
+        catch (error) {
+            rejectReadBatch(batch, error);
+        }
+    }
+    resolveReadBatch(batch, blob) {
+        for (const [key, reads] of batch.reads) {
+            const encoded = this.peekDirty(batch.bucket, key) ?? blob[key] ?? null;
+            const value = encoded === null
+                ? null
+                : decodeStorageValue(encoded, "SharedStorage.get");
+            for (const read of reads)
+                read.resolve(value);
+        }
+    }
+    async flushBucket(bucketKey, snapshot) {
+        if (snapshot.size === 0)
+            return;
+        const bucket = this.buckets.get(bucketKey);
+        if (!bucket)
+            return;
+        const context = await currentContext("SharedStorage.flush");
+        await storageGraphql(UPDATE_SHARED_DECK_STORAGE_MUTATION, sharedVariables(context.deckId, bucket, {
+            updates: updatesFromDirty(snapshot),
+        }), "updateSharedDeckStorage");
+        const dirty = this.dirtyBuckets.get(bucketKey);
+        if (!dirty)
+            return;
+        clearAcknowledgedDirty(dirty, snapshot);
+        if (dirty.size === 0)
+            this.dirtyBuckets.delete(bucketKey);
+    }
+    peekDirty(bucket, key) {
+        return this.dirtyBuckets.get(makeBucketKey(bucket))?.get(key);
+    }
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.flush();
+        }, FLUSH_INTERVAL_MS);
+    }
+}
+export const Storage = new PrivateStorageImpl();
+export const SharedStorage = new SharedStorageImpl();
+const DECK_STORAGE_QUERY = `
+  query CastleDeckStorage($deckId: ID!, $sessionId: ID) {
+    deckStorage(deckId: $deckId, sessionId: $sessionId)
+  }
+`;
+const UPDATE_DECK_STORAGE_MUTATION = `
+  mutation CastleUpdateDeckStorage(
+    $deckId: ID!,
+    $updates: [DeckStorageUpdateInput!]!,
+    $sessionId: ID
+  ) {
+    updateDeckStorage(deckId: $deckId, updates: $updates, sessionId: $sessionId)
+  }
+`;
+const SHARED_DECK_STORAGE_QUERY = `
+  query CastleSharedDeckStorage(
+    $deckId: ID!,
+    $keys: [String!]!,
+    $sessionId: ID,
+    $userId: ID
+  ) {
+    sharedDeckStorage(deckId: $deckId, keys: $keys, sessionId: $sessionId, userId: $userId)
+  }
+`;
+const UPDATE_SHARED_DECK_STORAGE_MUTATION = `
+  mutation CastleUpdateSharedDeckStorage(
+    $deckId: ID!,
+    $updates: [SharedDeckStorageUpdateInput!]!,
+    $sessionId: ID,
+    $userId: ID
+  ) {
+    updateSharedDeckStorage(
+      deckId: $deckId,
+      updates: $updates,
+      sessionId: $sessionId,
+      userId: $userId
+    )
+  }
+`;
+async function currentContext(operation) {
+    const deckId = await storageDeckId(operation);
+    const context = await getDeckContext();
+    return { deckId, sessionId: context.sessionId ?? undefined };
+}
+async function storageDeckId(operation) {
+    try {
+        return await requireDeckId(operation);
+    }
+    catch (error) {
+        if (error instanceof CastleError && error.code === "MISSING_DECK_ID") {
+            throw storageError("CASTLE_STORAGE_MISSING_DECK_ID", "Save this deck before using Castle storage.", operation);
+        }
+        throw error;
+    }
+}
+async function storageGraphql(query, variables, operation) {
+    const token = await requireAuthToken(operation);
+    return graphqlRequest(query, variables, {
+        operation,
+        requireAuth: true,
+        token,
+    });
+}
+async function readBucket(scope, userOrKey, maybeKey, operation) {
+    assertScope(scope, operation);
+    if (scope === "deck")
+        return withSession({ scope });
+    if (maybeKey)
+        return withSession({ scope, userId: userOrKey });
+    return writeBucket(scope, operation);
+}
+async function writeBucket(scope, operation) {
+    assertScope(scope, operation);
+    if (scope === "deck")
+        return withSession({ scope });
+    const auth = await getAuth();
+    if (!auth.userId) {
+        throw storageError("CASTLE_STORAGE_MISSING_USER_ID", "Castle user id is required for user-scoped shared storage.", operation);
+    }
+    return withSession({ scope, userId: auth.userId });
+}
+async function withSession(bucket) {
+    const context = await getDeckContext();
+    return { ...bucket, sessionId: context.sessionId ?? undefined };
+}
+function sharedVariables(deckId, bucket, extra) {
+    return {
+        deckId,
+        sessionId: bucket.sessionId,
+        userId: bucket.userId,
+        ...extra,
+    };
+}
+function updatesFromDirty(dirty) {
+    return Array.from(dirty, ([key, value]) => ({ key, value }));
+}
+function clearAcknowledgedDirty(dirty, acknowledged) {
+    for (const [key, value] of acknowledged) {
+        if (dirty.get(key) === value)
+            dirty.delete(key);
+    }
+}
+function decodeStorageBlob(blob, operation) {
+    return new Map(Object.entries(blob).map(([key, value]) => [
+        key,
+        decodeStorageValue(value, operation),
+    ]));
+}
+function decodeStorageValue(encoded, operation) {
+    try {
+        return JSON.parse(encoded);
+    }
+    catch {
+        throw storageError("CASTLE_STORAGE_PARSE_FAILED", "Stored Castle value is not valid JSON.", operation);
+    }
+}
+function encodeStorageValue(value, operation) {
+    try {
+        assertJsonValue(value, new Set(), operation);
+        return JSON.stringify(value);
+    }
+    catch (error) {
+        if (error instanceof CastleError)
+            throw error;
+        throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage values must be JSON.", operation);
+    }
+}
+function assertJsonValue(value, seen, operation) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return;
+        throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage numbers must be finite.", operation);
+    }
+    if (Array.isArray(value)) {
+        assertJsonArray(value, seen, operation);
+        return;
+    }
+    if (typeof value === "object") {
+        assertJsonObject(value, seen, operation);
+        return;
+    }
+    throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage values must be JSON.", operation);
+}
+function assertJsonArray(values, seen, operation) {
+    if (seen.has(values)) {
+        throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage values cannot be cyclic.", operation);
+    }
+    seen.add(values);
+    for (const value of values)
+        assertJsonValue(value, seen, operation);
+    seen.delete(values);
+}
+function assertJsonObject(value, seen, operation) {
+    if (seen.has(value)) {
+        throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage values cannot be cyclic.", operation);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw storageError("CASTLE_STORAGE_SERIALIZE_FAILED", "Castle storage objects must be plain JSON.", operation);
+    }
+    seen.add(value);
+    for (const child of Object.values(value))
+        assertJsonValue(child, seen, operation);
+    seen.delete(value);
+}
+function makeBucketKey(bucket) {
+    return `${bucket.scope}:${bucket.userId ?? ""}:${bucket.sessionId ?? ""}`;
+}
+function contextKey(deckId, sessionId) {
+    return `${deckId}:${sessionId ?? ""}`;
+}
+function assertScope(scope, operation) {
+    if (scope !== "deck" && scope !== "user") {
+        throw storageError("CASTLE_STORAGE_INVALID_SCOPE", 'SharedStorage scope must be "deck" or "user".', operation);
+    }
+}
+function rejectReadBatch(batch, error) {
+    for (const reads of batch.reads.values()) {
+        for (const read of reads)
+            read.reject(error);
+    }
+}
+function storageError(code, message, operation) {
+    return new CastleError({ code, message, operation });
+}

package/dist/time.d.ts

@@ -0,0 +1,17 @@
+export type CastleClockZone = "player" | "Castle";
+export interface CastleDateParts {
+    sec: number;
+    min: number;
+    hour: number;
+    day: number;
+    month: number;
+    year: number;
+    wday: number;
+    yday: number;
+    daysSinceCastleEpoch: number;
+}
+export interface CastleTimeApi {
+    getServerTime(): Promise<number>;
+    getServerDate(timezone?: CastleClockZone): Promise<CastleDateParts>;
+}
+export declare const Time: CastleTimeApi;

package/dist/time.js

@@ -0,0 +1,131 @@
+import { CastleError } from "./errors";
+import { graphqlRequest } from "./graphql";
+const SERVER_TIME_QUERY = `
+  query CastleServerTime {
+    serverTime {
+      timestamp
+      timezoneOffset
+      castleEpochData
+    }
+  }
+`;
+let serverTimeSnapshot = null;
+let serverTimePromise = null;
+export const Time = {
+    getServerTime,
+    getServerDate,
+};
+async function getServerTime() {
+    const snapshot = await syncServerTime();
+    return clientUnixSeconds() + snapshot.offsetSeconds;
+}
+async function getServerDate(timezone = "Castle") {
+    const operation = "Time.getServerDate";
+    const zone = clockZone(timezone, operation);
+    const snapshot = await syncServerTime();
+    return dateParts(clientUnixSeconds() + snapshot.offsetSeconds, zone, snapshot);
+}
+async function syncServerTime() {
+    if (serverTimeSnapshot)
+        return serverTimeSnapshot;
+    if (!serverTimePromise) {
+        serverTimePromise = fetchServerTime().then((snapshot) => {
+            serverTimeSnapshot = snapshot;
+            return snapshot;
+        });
+    }
+    return serverTimePromise;
+}
+async function fetchServerTime() {
+    const operation = "Time.getServerTime";
+    const data = await graphqlRequest(SERVER_TIME_QUERY, undefined, {
+        operation,
+    });
+    const timestamp = numberField(data.serverTime.timestamp, "serverTime.timestamp", operation);
+    const timezoneOffset = numberField(data.serverTime.timezoneOffset, "serverTime.timezoneOffset", operation);
+    const epochData = jsonObject(data.serverTime.castleEpochData, "serverTime.castleEpochData", operation);
+    return {
+        offsetSeconds: snappedOffset(timestamp - clientUnixSeconds()),
+        castleTimezoneOffsetMinutes: timezoneOffset,
+        daysSinceCastleEpoch: {
+            Castle: numberField(epochData.daysSinceServerTz, "castleEpochData.daysSinceServerTz", operation),
+            player: numberField(epochData.daysSinceUserTz, "castleEpochData.daysSinceUserTz", operation),
+        },
+    };
+}
+function dateParts(unixSeconds, timezone, snapshot) {
+    const shiftedSeconds = timezone === "Castle"
+        ? unixSeconds + snapshot.castleTimezoneOffsetMinutes * 60
+        : unixSeconds;
+    const date = new Date(shiftedSeconds * 1000);
+    return timezone === "Castle"
+        ? utcDateParts(date, snapshot.daysSinceCastleEpoch.Castle)
+        : localDateParts(date, snapshot.daysSinceCastleEpoch.player);
+}
+function utcDateParts(date, daysSinceCastleEpoch) {
+    return {
+        sec: date.getUTCSeconds(),
+        min: date.getUTCMinutes(),
+        hour: date.getUTCHours(),
+        day: date.getUTCDate(),
+        month: date.getUTCMonth() + 1,
+        year: date.getUTCFullYear(),
+        wday: date.getUTCDay() + 1,
+        yday: dayOfYear(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()),
+        daysSinceCastleEpoch,
+    };
+}
+function localDateParts(date, daysSinceCastleEpoch) {
+    return {
+        sec: date.getSeconds(),
+        min: date.getMinutes(),
+        hour: date.getHours(),
+        day: date.getDate(),
+        month: date.getMonth() + 1,
+        year: date.getFullYear(),
+        wday: date.getDay() + 1,
+        yday: dayOfYear(date.getFullYear(), date.getMonth(), date.getDate()),
+        daysSinceCastleEpoch,
+    };
+}
+function dayOfYear(year, monthIndex, day) {
+    const start = Date.UTC(year, 0, 1);
+    const current = Date.UTC(year, monthIndex, day);
+    return Math.floor((current - start) / 86400000) + 1;
+}
+function clockZone(timezone, operation) {
+    const normalized = timezone.trim().toLowerCase();
+    if (normalized === "castle")
+        return "Castle";
+    if (normalized === "player")
+        return "player";
+    throw new CastleError({
+        code: "UNSUPPORTED_TIMEZONE",
+        message: 'Time.getServerDate timezone must be "Castle" or "player".',
+        operation,
+    });
+}
+function clientUnixSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+function snappedOffset(offsetSeconds) {
+    return Math.abs(offsetSeconds) < 10 ? 0 : offsetSeconds;
+}
+function jsonObject(value, field, operation) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value))
+        return value;
+    throw new CastleError({
+        code: "GRAPHQL_BAD_DATA",
+        message: `Castle GraphQL field ${field} was not an object.`,
+        operation,
+    });
+}
+function numberField(value, field, operation) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    throw new CastleError({
+        code: "GRAPHQL_BAD_DATA",
+        message: `Castle GraphQL field ${field} was not a number.`,
+        operation,
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,3 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/user.d.ts

@@ -0,0 +1,9 @@
+export interface CastleUser {
+    userId: string;
+    username: string;
+    isActive: boolean;
+}
+export interface CastleUserApi {
+    getCurrent(): Promise<CastleUser>;
+}
+export declare const User: CastleUserApi;

package/dist/user.js

@@ -0,0 +1,58 @@
+import { requireAuthToken } from "./auth";
+import { CastleError } from "./errors";
+import { graphqlRequest } from "./graphql";
+const CURRENT_USER_QUERY = `
+  query CastleCurrentUser {
+    me {
+      userId
+      username
+    }
+  }
+`;
+let currentUser = null;
+let currentUserPromise = null;
+export const User = {
+    getCurrent,
+};
+async function getCurrent() {
+    if (currentUser)
+        return currentUser;
+    currentUserPromise ??= fetchCurrentUser().then((user) => {
+        currentUser = user;
+        return user;
+    });
+    return currentUserPromise;
+}
+async function fetchCurrentUser() {
+    const operation = "User.getCurrent";
+    const token = await requireAuthToken(operation);
+    const data = await graphqlRequest(CURRENT_USER_QUERY, undefined, {
+        operation,
+        requireAuth: true,
+        token,
+    });
+    if (!data.me) {
+        throw new CastleError({
+            code: "LOGIN_REQUIRED",
+            message: "Log in to Castle before using User.getCurrent().",
+            operation,
+        });
+    }
+    return normalizeCurrentUser(data.me, operation);
+}
+function normalizeCurrentUser(user, operation) {
+    return {
+        userId: requiredString(user.userId, "me.userId", operation),
+        username: requiredString(user.username, "me.username", operation),
+        isActive: true,
+    };
+}
+function requiredString(value, field, operation) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    throw new CastleError({
+        code: "GRAPHQL_BAD_DATA",
+        message: `Castle GraphQL response did not include ${field}.`,
+        operation,
+    });
+}

package/package.json

@@ -1,9 +1,36 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
-  "main": "castle.js",
+  "main": "dist/castle.js",
+  "types": "dist/castle.d.ts",
   "exports": {
-    ".": "./castle.js"
+    ".": {
+      "types": "./dist/castle.d.ts",
+      "default": "./dist/castle.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "check": "eslint . && jscpd && tsc --noEmit && tsc"
+  },
+  "jscpd": {
+    "path": [
+      "src"
+    ],
+    "threshold": 0,
+    "reporters": [
+      "consoleFull"
+    ]
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "jscpd": "^4.0.5",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0"
   }
 }