@indietabletop/appkit 4.0.0 → 4.1.1

package/lib/account/VerifyPage.tsx

@@ -17,20 +17,21 @@ import {
   LetterheadSubmitError,
   LetterheadTextField,
 } from "../LetterheadForm/index.tsx";
+import { useAppActions } from "../store/index.tsx";
 import type { CurrentUser } from "../types.ts";
 import { useForm } from "../use-form.ts";
-import type { EventHandler, EventHandlerWithReload } from "./types.ts";
+import type { AuthEventHandler } from "./types.ts";
 
 type SetStep = Dispatch<SetStateAction<VerifyStep>>;
 
 function InitialStep(props: {
   setStep: SetStep;
   currentUser: CurrentUser;
-  onLogout: EventHandlerWithReload;
   reload: () => void;
 }) {
-  const { setStep, onLogout, currentUser, reload } = props;
+  const { setStep, currentUser, reload } = props;
   const { email } = currentUser;
+  const { logout } = useAppActions();
 
   const client = useClient();
   const { form, submitName } = useForm({
@@ -62,7 +63,10 @@ function InitialStep(props: {
             Cannot complete verification?{" "}
             <Button
               className={interactiveText}
-              onClick={() => void onLogout({ reload })}
+              onClick={async () => {
+                await logout();
+                reload();
+              }}
             >
               Log out
             </Button>
@@ -130,7 +134,7 @@ function SubmitCodeStep(props: {
   );
 }
 
-function SuccessStep(props: { onClose?: EventHandler }) {
+function SuccessStep(props: { onClose?: AuthEventHandler }) {
   const { onClose } = props;
   const { hrefs } = useAppConfig();
 
@@ -163,7 +167,6 @@ type VerifyStep =
 
 export function VerifyAccountView(props: {
   currentUser: CurrentUser;
-  onLogout: EventHandlerWithReload;
   reload: () => void;
 
   /**
@@ -172,7 +175,7 @@ export function VerifyAccountView(props: {
    *
    * This is useful if this view is used within a modal dialog context.
    */
-  onClose?: EventHandler;
+  onClose?: AuthEventHandler;
 }) {
   const [step, setStep] = useState<VerifyStep>({ type: "INITIAL" });
 

package/lib/account/types.ts

@@ -1,7 +1,9 @@
-export type EventHandler = () => Promise<void> | void;
+import type { CurrentUser } from "../types.ts";
 
-export type EventHandlerWithReload = (options: {
-  reload: () => void;
+export type AuthEventHandler = () => Promise<void> | void;
+
+export type ClientLogoutHandler = (options: {
+  serverUser: CurrentUser;
 }) => Promise<void> | void;
 
 export type DefaultFormValues = {

package/lib/account/{useCurrentUserResult.tsx → useFetchCurrentUser.tsx}

@@ -3,7 +3,7 @@ import { useClient } from "../AppConfig/AppConfig.tsx";
 import { type Failure, Pending, type Success } from "../async-op.ts";
 import type { CurrentUser, FailurePayload } from "../types.ts";
 
-export function useCurrentUserResult(options?: {
+export function useFetchCurrentUser(options?: {
   /**
    * Optionally disable immediate fetch action.
    *

package/lib/async-op.ts

@@ -33,6 +33,8 @@ interface Operation<SuccessValue, FailureValue> {
     mapF: (failure: FailureValue) => F,
     mapP: () => P,
   ): S | F | P;
+
+  toJSON(): object;
 }
 
 export class Pending implements Operation<never, never> {
@@ -50,6 +52,7 @@ export class Pending implements Operation<never, never> {
   valueOrThrow(): never {
     throw new Error(
       `AsyncOp value was accessed but the op is in Pending state.`,
+      { cause: this },
     );
   }
 
@@ -64,6 +67,7 @@ export class Pending implements Operation<never, never> {
   failureValueOrThrow(): never {
     throw new Error(
       `AsyncOp failure value was accessed but the op is in Pending state.`,
+      { cause: this },
     );
   }
 
@@ -86,6 +90,10 @@ export class Pending implements Operation<never, never> {
   ): S | F | P {
     return mapP();
   }
+
+  toJSON() {
+    return { type: this.type };
+  }
 }
 
 export class Success<SuccessValue> implements Operation<SuccessValue, never> {
@@ -120,6 +128,7 @@ export class Success<SuccessValue> implements Operation<SuccessValue, never> {
   failureValueOrThrow(): never {
     throw new Error(
       `AsyncOp failure value was accessed but the op is in Success state.`,
+      { cause: this },
     );
   }
 
@@ -144,6 +153,13 @@ export class Success<SuccessValue> implements Operation<SuccessValue, never> {
   ): S | F | P {
     return mapS(this.value);
   }
+
+  toJSON() {
+    return {
+      type: this.type,
+      value: this.value,
+    };
+  }
 }
 
 export class Failure<FailureValue> implements Operation<never, FailureValue> {
@@ -166,6 +182,7 @@ export class Failure<FailureValue> implements Operation<never, FailureValue> {
   valueOrThrow(): never {
     throw new Error(
       `AsyncOp value was accessed but the op is in Failure state.`,
+      { cause: this },
     );
   }
 
@@ -200,6 +217,13 @@ export class Failure<FailureValue> implements Operation<never, FailureValue> {
   ): S | F | P {
     return mapF(this.failure);
   }
+
+  toJSON() {
+    return {
+      type: this.type,
+      failure: this.failure,
+    };
+  }
 }
 
 /**
@@ -252,3 +276,11 @@ export type AsyncOp<SuccessValue, FailureValue> =
   | Pending
   | Success<SuccessValue>
   | Failure<FailureValue>;
+
+export function fromTryCatch<T>(callback: () => T) {
+  try {
+    return new Success(callback());
+  } catch (cause) {
+    return new Failure(cause);
+  }
+}

package/lib/client.ts

@@ -2,6 +2,48 @@ import { type Infer, mask, object, string, Struct, unknown } from "superstruct";
 import { Failure, Success } from "./async-op.js";
 import { currentUser, redeemedPledge, sessionInfo } from "./structs.js";
 import type { CurrentUser, FailurePayload, SessionInfo } from "./types.js";
+import type { GangData, GangTombstone } from "./types/spacegits.ts";
+
+export type UserGameData = {
+  spacegits?: {
+    gangs?: (GangData | GangTombstone)[];
+  };
+};
+
+export type GameCode = keyof UserGameData;
+
+export type ClientEventType = keyof ClientEventMap;
+
+type ClientEventMap = {
+  /**
+   * Triggered every time currentUser is received.
+   */
+  currentUser: { currentUser: CurrentUser };
+
+  /**
+   * Triggered when new session info is received.
+   */
+  sessionInfo: { sessionInfo: SessionInfo };
+
+  /**
+   * Triggered when token refresh fails due to a 401 error.
+   */
+  sessionExpired: undefined;
+};
+
+type ClientEventArgs<T extends ClientEventType> =
+  ClientEventMap[T] extends undefined
+    ? [type: T]
+    : [type: T, detail: ClientEventMap[T]];
+
+export class ClientEvent<T extends keyof ClientEventMap> extends CustomEvent<
+  ClientEventMap[T]
+> {
+  constructor(...args: ClientEventArgs<T>) {
+    const [type, detail] = args;
+    super(type, { detail });
+  }
+}
 
 const logLevelToInt = {
   off: 0,
@@ -12,15 +54,31 @@ const logLevelToInt = {
 
 type LogLevel = keyof typeof logLevelToInt;
 
+type Primitives = string | boolean | number;
+
+function toParams(init: Record<string, Primitives | Array<Primitives>>) {
+  const params = new URLSearchParams();
+
+  const entries = Object.entries(init).flatMap(([key, value]) => {
+    return Array.isArray(value)
+      ? value.map((v) => [key, v] as const)
+      : [[key, value] as const];
+  });
+
+  for (const [key, value] of entries) {
+    params.append(key, value.toString());
+  }
+
+  return params;
+}
+
 export class IndieTabletopClient {
   origin: string;
-  private onCurrentUser?: (currentUser: CurrentUser) => void;
-  private onSessionInfo?: (sessionInfo: SessionInfo) => void;
-  private onSessionExpired?: () => void;
   private refreshTokenPromise?: Promise<
     Success<{ sessionInfo: SessionInfo }> | Failure<FailurePayload>
   >;
   private maxLogLevel: number;
+  private eventTarget: EventTarget;
 
   constructor(props: {
     apiOrigin: string;
@@ -52,11 +110,55 @@ export class IndieTabletopClient {
      */
     logLevel?: LogLevel;
   }) {
+    this.eventTarget = new EventTarget();
     this.origin = props.apiOrigin;
-    this.onCurrentUser = props.onCurrentUser;
-    this.onSessionInfo = props.onSessionInfo;
-    this.onSessionExpired = props.onSessionExpired;
     this.maxLogLevel = props.logLevel ? logLevelToInt[props.logLevel] : 1;
+
+    // If handlers were passed to the constructor, we set them up here. No need
+    // to clean them up, as if the instance is destroyed, the listeners will
+    // go with it.
+    const { onCurrentUser, onSessionInfo, onSessionExpired } = props;
+    if (onCurrentUser) {
+      this.addEventListener("currentUser", (event) => {
+        return onCurrentUser(event.detail.currentUser);
+      });
+    }
+    if (onSessionInfo) {
+      this.addEventListener("sessionInfo", (event) => {
+        return onSessionInfo(event.detail.sessionInfo);
+      });
+    }
+    if (onSessionExpired) {
+      this.addEventListener("sessionExpired", () => {
+        return onSessionExpired();
+      });
+    }
+  }
+
+  private dispatchEvent<T extends ClientEventType>(
+    ...args: ClientEventArgs<T>
+  ) {
+    this.eventTarget.dispatchEvent(new ClientEvent(...(args as [any, any])));
+  }
+
+  public addEventListener<T extends ClientEventType>(
+    type: T,
+    callback: (event: ClientEvent<T>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void {
+    this.eventTarget.addEventListener(type, callback as EventListener, options);
+  }
+
+  public removeEventListener<T extends ClientEventType>(
+    type: T,
+    callback: (event: ClientEvent<T>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void {
+    this.eventTarget.removeEventListener(
+      type,
+      callback as EventListener,
+      options,
+    );
   }
 
   private log(level: Exclude<LogLevel, "off">, ...messages: unknown[]) {
@@ -65,22 +167,55 @@ export class IndieTabletopClient {
     }
   }
 
-  protected async fetch<T, S>(
+  private async fetchWithTokenRefresh(...params: Parameters<typeof fetch>) {
+    const response = await fetch(...params);
+
+    if (response.status !== 401) {
+      return response;
+    }
+
+    const authHeader = response.headers.get("WWW-Authenticate");
+    if (!authHeader) {
+      return response;
+    }
+
+    if (
+      authHeader.includes("invalid_token") ||
+      authHeader.includes("invalid_request")
+    ) {
+      this.log("info", "Request failed due to a missing or expired token.");
+
+      const refresh = await this.refreshTokens();
+      if (refresh.isFailure) {
+        this.log("info", "Token refresh failed.");
+
+        // If refresh failed, return the original response.
+        return response;
+      }
+
+      // Tokens were refreshed, let's give it another go...
+      return await fetch(...params);
+    }
+
+    return response;
+  }
+
+  async fetch<T, S>(
     path: string,
     struct: Struct<T, S>,
     init?: RequestInit & { json?: object },
   ): Promise<Success<Infer<Struct<T, S>>> | Failure<FailurePayload>> {
-    // If json was provided, we stringify it. Otherwise we use body.
+    // If json was provided, we stringify it. Otherwise we use body as is.
     const body = init?.json ? JSON.stringify(init.json) : init?.body;
 
-    // If json was provided, we make sure that content type is correctly set.
-    const headers = init?.json
-      ? { ...init?.headers, "Content-Type": "application/json" }
-      : init?.headers;
+    const headers = new Headers(init?.headers);
+    if (init?.json) {
+      headers.set("Content-Type", "application/json");
+    }
 
     try {
-      const res = await fetch(`${this.origin}${path}`, {
-        // Defaults
+      const url = new URL(path, this.origin);
+      const res = await this.fetchWithTokenRefresh(url, {
         credentials: "include",
 
         // Overrides
@@ -113,33 +248,15 @@ export class IndieTabletopClient {
   }
 
   /**
-   * Fetches data and retries 401 failures after attempting to refresh tokens.
+   * @deprecated Use the instance `fetch` method instead. Token refresh
+   * is determined dynamically by server response.
    */
   protected async fetchWithAuth<T, S>(
     path: string,
     struct: Struct<T, S>,
     init?: RequestInit & { json?: object },
   ): Promise<Success<Infer<Struct<T, S>>> | Failure<FailurePayload>> {
-    const op = await this.fetch(path, struct, init);
-
-    if (op.isSuccess) {
-      return op;
-    }
-
-    if (op.failure.type === "API_ERROR" && op.failure.code === 401) {
-      this.log("info", "API request failed with error 401. Refreshing tokens.");
-
-      const refreshOp = await this.refreshTokens();
-
-      if (refreshOp.isSuccess) {
-        this.log("info", "Tokens refreshed. Retrying request.");
-        return await this.fetch(path, struct, init);
-      } else {
-        this.log("info", "Could not refresh tokens.");
-      }
-    }
-
-    return op;
+    return this.fetch(path, struct, init);
   }
 
   async login(payload: { email: string; password: string }) {
@@ -156,8 +273,9 @@ export class IndieTabletopClient {
     );
 
     if (result.isSuccess) {
-      this.onCurrentUser?.(result.value.currentUser);
-      this.onSessionInfo?.(result.value.sessionInfo);
+      const { currentUser, sessionInfo } = result.value;
+      this.dispatchEvent("currentUser", { currentUser });
+      this.dispatchEvent("sessionInfo", { sessionInfo });
     }
 
     return result;
@@ -194,8 +312,8 @@ export class IndieTabletopClient {
     );
 
     if (res.isSuccess) {
-      this.onCurrentUser?.(res.value.currentUser);
-      this.onSessionInfo?.(res.value.sessionInfo);
+      this.dispatchEvent("currentUser", { currentUser: res.value.currentUser });
+      this.dispatchEvent("sessionInfo", { sessionInfo: res.value.sessionInfo });
     }
 
     return res;
@@ -230,7 +348,9 @@ export class IndieTabletopClient {
     const result = await this.refreshTokenPromise;
 
     if (result.isSuccess) {
-      this.onSessionInfo?.(result.value.sessionInfo);
+      this.dispatchEvent("sessionInfo", {
+        sessionInfo: result.value.sessionInfo,
+      });
     }
 
     if (
@@ -238,7 +358,7 @@ export class IndieTabletopClient {
       result.failure.type === "API_ERROR" &&
       result.failure.code === 401
     ) {
-      this.onSessionExpired?.();
+      this.dispatchEvent("sessionExpired");
     }
 
     // Make sure to reset the shared reference so that subsequent invocations
@@ -319,10 +439,20 @@ export class IndieTabletopClient {
   }
 
   async getCurrentUser() {
-    const result = await this.fetchWithAuth(`/v1/users/me`, currentUser());
+    const result = await this.fetch(`/v1/users/me`, currentUser());
 
     if (result.isSuccess) {
-      this.onCurrentUser?.(result.value);
+      this.dispatchEvent("currentUser", { currentUser: result.value });
+    }
+
+    if (
+      result.isFailure &&
+      result.failure.type === "API_ERROR" &&
+      result.failure.code === 404
+    ) {
+      // The user no longer exists, so even though they might have a temporarily
+      // valid session, we want to behave as if the session has expired.
+      this.dispatchEvent("sessionExpired");
     }
 
     return result;
@@ -401,4 +531,44 @@ export class IndieTabletopClient {
       { method: "PUT" },
     );
   }
+
+  async pullUserData(props: {
+    sinceTs: number | null;
+    include: GameCode | GameCode[];
+    expectCurrentUserId: string;
+  }) {
+    const params = toParams({
+      sinceTs: props.sinceTs ?? 0,
+      include: props.include,
+      omitDeleted: !props.sinceTs,
+      expectCurrentUserId: props.expectCurrentUserId,
+    });
+
+    return await this.fetch(
+      `/v1/me/data?${params}`,
+      unknown() as Struct<UserGameData, null>,
+    );
+  }
+
+  async pushUserData(props: {
+    currentSyncTs: number;
+    pullSinceTs: number | null;
+    data: UserGameData;
+    expectCurrentUserId: string | null | undefined;
+  }) {
+    return await this.fetch(
+      `/v1/me/data`,
+      unknown() as Struct<UserGameData, null>,
+      {
+        method: "PATCH",
+        json: {
+          data: props.data,
+          syncedTs: props.currentSyncTs,
+          pullSinceTs: props.pullSinceTs ?? 0,
+          pullOmitDeleted: !props.pullSinceTs,
+          expectCurrentUserId: props.expectCurrentUserId,
+        },
+      },
+    );
+  }
 }

package/lib/createSafeStorage.ts

@@ -0,0 +1,91 @@
+import { type Struct, validate } from "superstruct";
+import { fromTryCatch } from "./async-op.ts";
+
+type AnyStruct = Struct<any, any>;
+
+type StructsConfig = Record<string, AnyStruct>;
+
+type SafeStorage<T extends Record<string, AnyStruct>> = ReturnType<
+  typeof createSafeStorage<T>
+>;
+
+export type SafeStorageKey<T extends SafeStorage<StructsConfig>> = ReturnType<
+  T["keys"]
+>[number];
+
+type StructValue<T> = T extends Struct<infer V> ? V : never;
+
+/**
+ * Creates an object with an interface similar to localStorage, but that
+ * enforces that values are parsed and validated before being retrieved,
+ * stringified when being set, and that both keys and values typecheck.
+ *
+ * @example
+ * ```ts
+ * const safeStorage = createSafeStorage({
+ *   currentUser: currentUser(),
+ *   sessionInfo: sessionInfo(),
+ *   lastSuccessfulSyncTs: number(),
+ * });
+ *
+ * safeStorage.getItem("currentUser") // Will be valid current user or `null`
+ * safeStorage.setItem("currentUser", { ... }) // Typechecked key and value
+ * safeStorage.removeItem("currentUser") // Typechecked key
+ * safeStorage.clear() // Removes all "owned" keys
+ *
+ * ```
+ */
+export function createSafeStorage<T extends StructsConfig>(structs: T) {
+  return {
+    getItem<K extends keyof T & string>(key: K) {
+      const struct = structs[key];
+      if (!struct) {
+        throw new Error(`No struct found for ${key}`);
+      }
+
+      const storedValue = localStorage.getItem(key);
+
+      if (storedValue === null) {
+        return null;
+      }
+
+      const parsedResult = fromTryCatch<unknown>(() => JSON.parse(storedValue));
+
+      if (parsedResult.isFailure) {
+        console.warn(`Could not parse localStorage value at key '${key}'.`);
+        return null;
+      }
+
+      const [error, value] = validate(parsedResult.value, struct, {
+        coerce: true,
+        mask: true,
+      });
+
+      if (error) {
+        console.warn(
+          `Validation failed for localStorage value at key '${key}'. ${error.message}`,
+        );
+      }
+
+      return value as StructValue<T[K]> | null;
+    },
+
+    setItem<K extends keyof T & string>(key: K, value: StructValue<T[K]>) {
+      localStorage.setItem(key, JSON.stringify(value));
+    },
+
+    removeItem(key: keyof T & string) {
+      localStorage.removeItem(key);
+    },
+
+    clear() {
+      for (const key in structs) {
+        localStorage.removeItem(key);
+      }
+    },
+
+    keys() {
+      return Object.keys(structs) as (keyof T)[];
+    },
+  };
+}

package/lib/index.ts

@@ -43,6 +43,7 @@ export * from "./caught-value.ts";
 export * from "./class-names.ts";
 export * from "./client.ts";
 export * from "./copyrightRange.ts";
+export * from "./createSafeStorage.ts";
 export * from "./failureMessages.ts";
 export * from "./groupBy.ts";
 export * from "./HistoryState.ts";
@@ -61,5 +62,9 @@ export * from "./unique.ts";
 export * from "./utm.ts";
 export * from "./validations.ts";
 
+// Structs
+export * from "./types/spacegits.ts";
+
 // Other
 export * from "./ModernIDB/index.ts";
+export * from "./store/index.tsx";