@indietabletop/appkit 0.3.1 → 1.0.1

package/README.md

@@ -7,6 +7,10 @@ A collection of modules used in Indie Tabletop Club's apps.
 
 ## Contents
 
+### Classes
+
+- IndieTabletopClient
+
 ### Hooks
 
 - useAsyncPp

package/dist/client.d.ts

@@ -0,0 +1,127 @@
+import { Failure, Success } from "@indietabletop/appkit/async-op";
+import { Infer, Struct } from "superstruct";
+import { CurrentUser, FailurePayload, SessionInfo } from "./types.js";
+export declare class IndieTabletopClient {
+    origin: string;
+    private onCurrentUser?;
+    private onSessionInfo?;
+    private onSessionExpired?;
+    private refreshTokenPromise?;
+    constructor(props: {
+        apiOrigin: string;
+        /**
+         * Runs every time the current user is fetched from the API. Typically, this
+         * happens during login, signup, and when the current user is fetched.
+         */
+        onCurrentUser?: (currentUser: CurrentUser) => void;
+        /**
+         * Runs ever time new session info is fetched from the API. Typically, this
+         * happends during login, signup, and when tokens are refreshed.
+         */
+        onSessionInfo?: (sessionInfo: SessionInfo) => void;
+        /**
+         * Runs when token refresh is attempted, but fails due to 401 error.
+         */
+        onSessionExpired?: () => void;
+    });
+    protected fetch<T, S>(path: string, struct: Struct<T, S>, init?: RequestInit & {
+        json?: object;
+    }): Promise<Success<Infer<Struct<T, S>>> | Failure<FailurePayload>>;
+    /**
+     * Fetches data and retries 401 failures after attempting to refresh tokens.
+     */
+    protected fetchWithAuth<T, S>(path: string, struct: Struct<T, S>, init?: RequestInit & {
+        json?: object;
+    }): Promise<Success<Infer<Struct<T, S>>> | Failure<FailurePayload>>;
+    login(payload: {
+        email: string;
+        password: string;
+    }): Promise<Failure<FailurePayload> | Success<{
+        sessionInfo: {
+            expiresTs: number;
+            createdTs: number;
+        };
+        currentUser: {
+            id: string;
+            email: string;
+            isVerified: boolean;
+            prefersScrollbarVisibility?: "ALWAYS" | undefined;
+        };
+    }>>;
+    logout(): Promise<Failure<FailurePayload> | Success<{
+        message: string;
+    }>>;
+    join(payload: {
+        email: string;
+        password: string;
+        acceptedTos: boolean;
+    }): Promise<Failure<FailurePayload> | Success<{
+        sessionInfo: {
+            expiresTs: number;
+            createdTs: number;
+        };
+        currentUser: {
+            id: string;
+            email: string;
+            isVerified: boolean;
+            prefersScrollbarVisibility?: "ALWAYS" | undefined;
+        };
+        tokenId: string;
+    }>>;
+    /**
+     * Triggers token refresh process.
+     *
+     * Note that we do not want to perform multiple concurrent token refresh
+     * actions, as that will result in unnecessary 401s. For this reason, a
+     * reference to t
+     */
+    refreshTokens(): Promise<Success<{
+        sessionInfo: SessionInfo;
+    }> | Failure<FailurePayload>>;
+    requestPasswordReset(payload: {
+        email: string;
+    }): Promise<Failure<FailurePayload> | Success<{
+        message: string;
+        tokenId: string;
+    }>>;
+    checkPasswordResetCode(payload: {
+        tokenId: string;
+        code: string;
+    }): Promise<Failure<FailurePayload> | Success<{
+        message: string;
+    }>>;
+    setNewPassword(payload: {
+        tokenId: string;
+        code: string;
+        password: string;
+    }): Promise<Failure<FailurePayload> | Success<{
+        message: string;
+    }>>;
+    requestUserVerification(): Promise<Failure<FailurePayload> | Success<{
+        message: string;
+        tokenId: string;
+    }>>;
+    verifyUser(payload: {
+        tokenId: string;
+        code: string;
+    }): Promise<Failure<FailurePayload> | Success<{
+        message: string;
+    }>>;
+    getCurrentUser(): Promise<Failure<FailurePayload> | Success<{
+        sessionInfo: {
+            expiresTs: number;
+            createdTs: number;
+        };
+        currentUser: {
+            id: string;
+            email: string;
+            isVerified: boolean;
+            prefersScrollbarVisibility?: "ALWAYS" | undefined;
+        };
+    }> | Success<{
+        id: string;
+        email: string;
+        isVerified: boolean;
+        prefersScrollbarVisibility?: "ALWAYS" | undefined;
+    }>>;
+}

package/dist/client.js

@@ -0,0 +1,211 @@
+import { Failure, Success } from "@indietabletop/appkit/async-op";
+import { mask, object, string } from "superstruct";
+import { currentUser, sessionInfo } from "./structs.js";
+export class IndieTabletopClient {
+    constructor(props) {
+        Object.defineProperty(this, "origin", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onCurrentUser", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onSessionInfo", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onSessionExpired", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "refreshTokenPromise", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.origin = props.apiOrigin;
+        this.onCurrentUser = props.onCurrentUser;
+        this.onSessionInfo = props.onSessionInfo;
+        this.onSessionExpired = props.onSessionExpired;
+    }
+    async fetch(path, struct, init) {
+        // If json was provided, we stringify it. Otherwise we use body.
+        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;
+        try {
+            const res = await fetch(`${this.origin}${path}`, {
+                // Defaults
+                credentials: "include",
+                // Overrides
+                ...init,
+                body,
+                headers,
+            });
+            if (!res.ok) {
+                return new Failure({
+                    type: "API_ERROR",
+                    code: res.status,
+                });
+            }
+            const data = mask(await res.json(), struct);
+            return new Success(data);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                return new Failure({ type: "NETWORK_ERROR" });
+            }
+            return new Failure({ type: "UNKNOWN_ERROR" });
+        }
+    }
+    /**
+     * Fetches data and retries 401 failures after attempting to refresh tokens.
+     */
+    async fetchWithAuth(path, struct, init) {
+        const op = await this.fetch(path, struct, init);
+        if (op.isSuccess) {
+            return op;
+        }
+        if (op.failure.type === "API_ERROR" && op.failure.code === 401) {
+            console.info("API request failed with error 401. Refreshing tokens.");
+            const refreshOp = await this.refreshTokens();
+            if (refreshOp.isSuccess) {
+                console.info("Tokens refreshed. Retrying request.");
+                return await this.fetch(path, struct, init);
+            }
+            else {
+                console.info("Could not refresh tokens.");
+            }
+        }
+        return op;
+    }
+    async login(payload) {
+        const result = await this.fetch("/v1/sessions", object({
+            currentUser: currentUser(),
+            sessionInfo: sessionInfo(),
+        }), {
+            method: "POST",
+            json: { email: payload.email, plaintextPassword: payload.password },
+        });
+        if (result.isSuccess) {
+            this.onCurrentUser?.(result.value.currentUser);
+            this.onSessionInfo?.(result.value.sessionInfo);
+        }
+        return result;
+    }
+    async logout() {
+        return await this.fetch("/v1/sessions", object({ message: string() }), {
+            method: "DELETE",
+        });
+    }
+    async join(payload) {
+        const res = await this.fetch("/v1/users", object({
+            currentUser: currentUser(),
+            sessionInfo: sessionInfo(),
+            tokenId: string(),
+        }), {
+            method: "POST",
+            json: {
+                email: payload.email,
+                plaintextPassword: payload.password,
+                acceptedTos: payload.acceptedTos,
+            },
+        });
+        if (res.isSuccess) {
+            this.onCurrentUser?.(res.value.currentUser);
+            this.onSessionInfo?.(res.value.sessionInfo);
+        }
+        return res;
+    }
+    /**
+     * Triggers token refresh process.
+     *
+     * Note that we do not want to perform multiple concurrent token refresh
+     * actions, as that will result in unnecessary 401s. For this reason, a
+     * reference to t
+     */
+    async refreshTokens() {
+        // If there is an ongoing token refresh in progress return that. This should
+        // only deal the response payload, none of the side-effects and cleanup,
+        // which will be handled by the initial invocation.
+        const ongoingRequest = this.refreshTokenPromise;
+        if (ongoingRequest) {
+            console.info("Token refresh ongoing. Reusing existing promise.");
+            return await ongoingRequest;
+        }
+        // Cache the promise on an instance property to share a reference from
+        // other potential invocations.
+        this.refreshTokenPromise = this.fetch("/v1/sessions/access-tokens", object({ sessionInfo: sessionInfo() }), { method: "POST" });
+        const result = await this.refreshTokenPromise;
+        if (result.isSuccess) {
+            this.onSessionInfo?.(result.value.sessionInfo);
+        }
+        if (result.isFailure &&
+            result.failure.type === "API_ERROR" &&
+            result.failure.code === 401) {
+            this.onSessionExpired?.();
+        }
+        // Make sure to reset the shared reference so that subsequent invocations
+        // once again initiate token refresh.
+        delete this.refreshTokenPromise;
+        return result;
+    }
+    async requestPasswordReset(payload) {
+        return await this.fetch(`/v1/password-reset-tokens`, object({ message: string(), tokenId: string() }), { method: "POST", json: payload });
+    }
+    async checkPasswordResetCode(payload) {
+        const queryParams = new URLSearchParams({ plaintextCode: payload.code });
+        return await this.fetch(`/v1/password-reset-tokens/${payload.tokenId}?${queryParams}`, object({ message: string() }), { method: "GET" });
+    }
+    async setNewPassword(payload) {
+        const queryParams = new URLSearchParams({ plaintextCode: payload.code });
+        return await this.fetch(`/v1/password-reset-tokens/${payload.tokenId}?${queryParams}`, object({ message: string() }), { method: "PUT", json: { plaintextPassword: payload.password } });
+    }
+    async requestUserVerification() {
+        return await this.fetch(`/v1/user-verification-tokens`, object({ message: string(), tokenId: string() }), { method: "POST" });
+    }
+    async verifyUser(payload) {
+        const queryParams = new URLSearchParams({ plaintextCode: payload.code });
+        const req = await this.fetch(`/v1/user-verification-tokens/${payload.tokenId}?${queryParams}`, object({ message: string() }), { method: "PUT" });
+        if (req.isSuccess) {
+            await this.refreshTokens();
+            await this.getCurrentUser();
+        }
+        return req;
+    }
+    async getCurrentUser() {
+        const result = await this.fetchWithAuth(`/v1/users/me`, currentUser());
+        if (result.isSuccess) {
+            this.onCurrentUser?.(result.value);
+        }
+        // If /users/me request failed with 401 error, try again with the Ory
+        // endpoint for legacy users. This code block can be removed once Ory
+        // users are fully migrated.
+        if (result.isFailure &&
+            result.failure.type === "API_ERROR" &&
+            result.failure.code === 401) {
+            const oryR = await this.fetch(`/v1/users/ory`, object({
+                currentUser: currentUser(),
+                sessionInfo: sessionInfo(),
+            }));
+            if (oryR.isSuccess) {
+                this.onCurrentUser?.(oryR.value.currentUser);
+                this.onSessionInfo?.(oryR.value.sessionInfo);
+            }
+            return oryR;
+        }
+        return result;
+    }
+}

package/dist/structs.d.ts

@@ -0,0 +1,20 @@
+export declare function currentUser(): import("superstruct").Struct<{
+    id: string;
+    email: string;
+    isVerified: boolean;
+    prefersScrollbarVisibility?: "ALWAYS" | undefined;
+}, {
+    id: import("superstruct").Struct<string, null>;
+    email: import("superstruct").Struct<string, null>;
+    isVerified: import("superstruct").Struct<boolean, null>;
+    prefersScrollbarVisibility: import("superstruct").Struct<"ALWAYS" | undefined, {
+        ALWAYS: "ALWAYS";
+    }>;
+}>;
+export declare function sessionInfo(): import("superstruct").Struct<{
+    expiresTs: number;
+    createdTs: number;
+}, {
+    expiresTs: import("superstruct").Struct<number, null>;
+    createdTs: import("superstruct").Struct<number, null>;
+}>;

package/dist/structs.js

@@ -0,0 +1,15 @@
+import { boolean, enums, number, object, optional, string } from "superstruct";
+export function currentUser() {
+    return object({
+        id: string(),
+        email: string(),
+        isVerified: boolean(),
+        prefersScrollbarVisibility: optional(enums(["ALWAYS"])),
+    });
+}
+export function sessionInfo() {
+    return object({
+        expiresTs: number(),
+        createdTs: number(),
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,10 @@
+import { Infer } from "superstruct";
+import { currentUser, sessionInfo } from "./structs.js";
+export type CurrentUser = Infer<ReturnType<typeof currentUser>>;
+export type SessionInfo = Infer<ReturnType<typeof sessionInfo>>;
+export type FailurePayload = {
+    type: "API_ERROR";
+    code: number;
+} | {
+    type: "NETWORK_ERROR" | "UNKNOWN_ERROR";
+};

package/dist/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indietabletop/appkit",
-  "version": "0.3.1",
+  "version": "1.0.1",
   "description": "A collection of modules used in apps built by Indie Tabletop Club",
   "private": false,
   "type": "module",
@@ -19,12 +19,15 @@
   "repository": "github:indietabletop/appkit",
   "license": "MIT",
   "peerDependencies": {
-    "react": "^18.0.0"
+    "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "^18.3.12",
+    "@types/react": "^19.0.8",
     "np": "^10.1.0",
     "typescript": "^5.7.2",
     "vitest": "^2.1.6"
+  },
+  "dependencies": {
+    "superstruct": "^2.0.2"
   }
 }