@stackframe/stack-shared 2.4.13 → 2.4.20

package/dist/sessions.js

@@ -0,0 +1,146 @@
+import { Store } from "./utils/stores";
+export class AccessToken {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+}
+export class RefreshToken {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+}
+/**
+ * An InternalSession represents a user's session, which may or may not be valid. It may contain an access token, a refresh token, or both.
+ *
+ * A session never changes which user or session it belongs to, but the tokens in it may change over time.
+ */
+export class InternalSession {
+    _options;
+    /**
+    * Each session has a session key that depends on the tokens inside. If the session has a refresh token, the session key depends only on the refresh token. If the session does not have a refresh token, the session key depends only on the access token.
+    *
+    * Multiple Session objects may have the same session key, which implies that they represent the same session by the same user. Furthermore, a session's key never changes over the lifetime of a session object.
+    *
+    * This is useful for caching and indexing sessions.
+    */
+    sessionKey;
+    /**
+     * An access token that is not known to be invalid (ie. may be valid, but may have expired).
+     */
+    _accessToken;
+    _refreshToken;
+    /**
+     * Whether the session as a whole is known to be invalid. Used as a cache to avoid making multiple requests to the server (sessions never go back to being valid after being invalidated).
+     *
+     * Applies to both the access token and the refresh token (it is possible for the access token to be invalid but the refresh token to be valid, in which case the session is still valid).
+     */
+    _knownToBeInvalid = new Store(false);
+    _refreshPromise = null;
+    constructor(_options) {
+        this._options = _options;
+        this._accessToken = new Store(_options.accessToken ? new AccessToken(_options.accessToken) : null);
+        this._refreshToken = _options.refreshToken ? new RefreshToken(_options.refreshToken) : null;
+        this.sessionKey = InternalSession.calculateSessionKey({ accessToken: _options.accessToken ?? null, refreshToken: _options.refreshToken });
+    }
+    static calculateSessionKey(ofTokens) {
+        if (ofTokens.refreshToken) {
+            return `refresh-${ofTokens.refreshToken}`;
+        }
+        else if (ofTokens.accessToken) {
+            return `access-${ofTokens.accessToken}`;
+        }
+        else {
+            return "not-logged-in";
+        }
+    }
+    /**
+     * Marks the session object as invalid, meaning that the refresh and access tokens can no longer be used.
+     */
+    markInvalid() {
+        this._accessToken.set(null);
+        this._knownToBeInvalid.set(true);
+    }
+    onInvalidate(callback) {
+        return this._knownToBeInvalid.onChange(() => callback());
+    }
+    /**
+     * Returns the access token if it is found in the cache, fetching it otherwise.
+     *
+     * This is usually the function you want to call to get an access token. When using the access token, you should catch errors that occur if it expires, and call `markAccessTokenExpired` to mark the token as expired if so (after which a call to this function will always refetch the token).
+     *
+     * @returns null if the session is known to be invalid, cached tokens if they exist in the cache (which may or may not be valid still), or new tokens otherwise.
+     */
+    async getPotentiallyExpiredTokens() {
+        const accessToken = await this._getPotentiallyExpiredAccessToken();
+        return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;
+    }
+    /**
+     * Fetches new tokens that are, at the time of fetching, guaranteed to be valid.
+     *
+     * The newly generated tokens are shortlived, so it's good practice not to rely on their validity (if possible). However, this function is useful in some cases where you only want to pass access tokens to a service, and you want to make sure said access token has the longest possible lifetime.
+     *
+     * In most cases, you should prefer `getPotentiallyExpiredTokens` with a fallback to `markAccessTokenExpired` and a retry mechanism if the endpoint rejects the token.
+     *
+     * @returns null if the session is known to be invalid, or new tokens otherwise (which, at the time of fetching, are guaranteed to be valid).
+     */
+    async fetchNewTokens() {
+        const accessToken = await this._getNewlyFetchedAccessToken();
+        return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;
+    }
+    markAccessTokenExpired(accessToken) {
+        if (this._accessToken.get() === accessToken) {
+            this._accessToken.set(null);
+        }
+    }
+    /**
+     * Note that a callback invocation with `null` does not mean the session has been invalidated; the access token may just have expired. Use `onInvalidate` to detect invalidation.
+     */
+    onAccessTokenChange(callback) {
+        return this._accessToken.onChange(callback);
+    }
+    /**
+     * @returns An access token (cached if possible), or null if the session either does not represent a user or the session is invalid.
+     */
+    async _getPotentiallyExpiredAccessToken() {
+        const oldAccessToken = this._accessToken.get();
+        if (oldAccessToken)
+            return oldAccessToken;
+        if (!this._refreshToken)
+            return null;
+        if (this._knownToBeInvalid.get())
+            return null;
+        // refresh access token
+        if (!this._refreshPromise) {
+            this._refreshAndSetRefreshPromise(this._refreshToken);
+        }
+        return await this._refreshPromise;
+    }
+    /**
+     * You should prefer `getPotentiallyExpiredAccessToken` in almost all cases.
+     *
+     * @returns A newly fetched access token (never read from cache), or null if the session either does not represent a user or the session is invalid.
+     */
+    async _getNewlyFetchedAccessToken() {
+        if (!this._refreshToken)
+            return null;
+        if (this._knownToBeInvalid.get())
+            return null;
+        this._refreshAndSetRefreshPromise(this._refreshToken);
+        return await this._refreshPromise;
+    }
+    _refreshAndSetRefreshPromise(refreshToken) {
+        let refreshPromise = this._options.refreshAccessTokenCallback(refreshToken).then((accessToken) => {
+            if (refreshPromise === this._refreshPromise) {
+                this._refreshPromise = null;
+                this._accessToken.set(accessToken);
+                if (!accessToken) {
+                    this.markInvalid();
+                }
+            }
+            return accessToken;
+        });
+        this._refreshPromise = refreshPromise;
+    }
+}

package/dist/utils/crypto.js

@@ -1,4 +1,5 @@
 import { encodeBase32 } from "./bytes";
+import { globalVar } from "./globals";
 /**
  * Generates a secure alphanumeric string using the system's cryptographically secure
  * random number generator.
@@ -6,7 +7,7 @@ import { encodeBase32 } from "./bytes";
 export function generateSecureRandomString(minBitsOfEntropy = 224) {
     const base32CharactersCount = Math.ceil(minBitsOfEntropy / 5);
     const bytesCount = Math.ceil(base32CharactersCount * 5 / 8);
-    const randomBytes = globalThis.crypto.getRandomValues(new Uint8Array(bytesCount));
+    const randomBytes = globalVar.crypto.getRandomValues(new Uint8Array(bytesCount));
     const str = encodeBase32(randomBytes);
     return str.slice(str.length - base32CharactersCount).toLowerCase();
 }

package/dist/utils/dom.js

@@ -4,5 +4,5 @@ export function hasClickableParent(element) {
         return false;
     if (parent.dataset.n2Clickable)
         return true;
-    return !!element.parentElement && hasClickableParent(element.parentElement);
+    return hasClickableParent(element.parentElement);
 }

package/dist/utils/env.d.ts

@@ -1,3 +1,4 @@
+export declare function isBrowserLike(): boolean;
 /**
  * Returns the environment variable with the given name, throwing an error if it's undefined or the empty string.
  */

package/dist/utils/env.js

@@ -1,10 +1,13 @@
 import { throwErr } from "./errors";
 import { deindent } from "./strings";
+export function isBrowserLike() {
+    return typeof window !== "undefined" && typeof document !== "undefined" && typeof document.createElement !== "undefined";
+}
 /**
  * Returns the environment variable with the given name, throwing an error if it's undefined or the empty string.
  */
 export function getEnvVariable(name) {
-    if (typeof window !== 'undefined') {
+    if (isBrowserLike()) {
         throw new Error(deindent `
       Can't use getEnvVariable on the client because Next.js transpiles expressions of the kind process.env.XYZ at build-time on the client.
     

package/dist/utils/errors.js

@@ -1,3 +1,4 @@
+import { globalVar } from "./globals";
 export function throwErr(...args) {
     if (typeof args[0] === "string") {
         throw new StackAssertionError(args[0], args[1]);
@@ -29,6 +30,10 @@ export function registerErrorSink(sink) {
 registerErrorSink((location, ...args) => {
     console.error(`Error in ${location}:`, ...args);
 });
+registerErrorSink((location, error, ...args) => {
+    globalVar.stackCapturedErrors = globalVar.stackCapturedErrors ?? [];
+    globalVar.stackCapturedErrors.push({ location, error: args, extraArgs: args });
+});
 export function captureError(location, error) {
     for (const sink of errorSinks) {
         sink(location, error);

package/dist/utils/globals.js

@@ -1,6 +1,6 @@
 const globalVar = typeof globalThis !== 'undefined' ? globalThis :
-    typeof window !== 'undefined' ? window :
-        typeof global !== 'undefined' ? global :
+    typeof global !== 'undefined' ? global :
+        typeof window !== 'undefined' ? window :
             typeof self !== 'undefined' ? self :
                 {};
 export { globalVar, };

package/dist/utils/promises.d.ts

@@ -18,8 +18,10 @@ export declare function pending<T>(promise: Promise<T>, options?: {
 }): ReactPromise<T>;
 export declare function wait(ms: number): Promise<void>;
 export declare function waitUntil(date: Date): Promise<void>;
+export declare function runAsynchronouslyWithAlert(...args: Parameters<typeof runAsynchronously>): void;
 export declare function runAsynchronously(promiseOrFunc: void | Promise<unknown> | (() => void | Promise<unknown>) | undefined, options?: {
-    ignoreErrors?: boolean;
+    noErrorLogging?: boolean;
+    onError?: (error: Error) => void;
 }): void;
 declare class TimeoutError extends Error {
     readonly ms: number;

package/dist/utils/promises.js

@@ -75,6 +75,15 @@ class ErrorDuringRunAsynchronously extends Error {
         this.name = "ErrorDuringRunAsynchronously";
     }
 }
+export function runAsynchronouslyWithAlert(...args) {
+    return runAsynchronously(args[0], {
+        ...args[1],
+        onError: error => {
+            alert(`An unhandled error occurred. Please ${process.env.NODE_ENV === "development" ? `check the browser console for the full error. ${error}` : "report this to the developer."}`);
+            args[1]?.onError?.(error);
+        },
+    }, ...args.slice(2));
+}
 export function runAsynchronously(promiseOrFunc, options = {}) {
     if (typeof promiseOrFunc === "function") {
         promiseOrFunc = promiseOrFunc();
@@ -86,7 +95,8 @@ export function runAsynchronously(promiseOrFunc, options = {}) {
         }, {
             cause: error,
         });
-        if (!options.ignoreErrors) {
+        options.onError?.(newError);
+        if (!options.noErrorLogging) {
             captureError("runAsynchronously", newError);
         }
     });

package/dist/utils/proxies.d.ts

@@ -0,0 +1 @@
+export declare function logged<T extends object>(name: string, toLog: T, options?: {}): T;

package/dist/utils/proxies.js

@@ -0,0 +1,59 @@
+import { nicify } from "./strings";
+export function logged(name, toLog, options = {}) {
+    const proxy = new Proxy(toLog, {
+        get(target, prop, receiver) {
+            const orig = Reflect.get(target, prop, receiver);
+            if (typeof orig === "function") {
+                return function (...args) {
+                    const success = (v, isPromise) => console.debug(`logged(...): Called ${name}.${String(prop)}(${args.map(a => nicify(a)).join(", ")}) => ${isPromise ? "Promise<" : ""}${nicify(result)}${isPromise ? ">" : ""}`, { this: this, args, promise: isPromise ? result : false, result: v, trace: new Error() });
+                    const error = (e, isPromise) => console.debug(`logged(...): Error in ${name}.${String(prop)}(${args.map(a => nicify(a)).join(", ")})`, { this: this, args, promise: isPromise ? result : false, error: e, trace: new Error() });
+                    let result;
+                    try {
+                        result = orig.apply(this, args);
+                    }
+                    catch (e) {
+                        error(e, false);
+                        throw e;
+                    }
+                    if (result instanceof Promise) {
+                        result.then((v) => success(v, true)).catch((e) => error(e, true));
+                    }
+                    else {
+                        success(result, false);
+                    }
+                    return result;
+                };
+            }
+            return orig;
+        },
+        set(target, prop, value) {
+            console.log(`Setting ${name}.${String(prop)} to ${value}`);
+            return Reflect.set(target, prop, value);
+        },
+        apply(target, thisArg, args) {
+            console.log(`Calling ${name}(${JSON.stringify(args).slice(1, -1)})`);
+            return Reflect.apply(target, thisArg, args);
+        },
+        construct(target, args, newTarget) {
+            console.log(`Constructing ${name}(${JSON.stringify(args).slice(1, -1)})`);
+            return Reflect.construct(target, args, newTarget);
+        },
+        defineProperty(target, prop, descriptor) {
+            console.log(`Defining ${name}.${String(prop)} as ${JSON.stringify(descriptor)}`);
+            return Reflect.defineProperty(target, prop, descriptor);
+        },
+        deleteProperty(target, prop) {
+            console.log(`Deleting ${name}.${String(prop)}`);
+            return Reflect.deleteProperty(target, prop);
+        },
+        setPrototypeOf(target, prototype) {
+            console.log(`Setting prototype of ${name} to ${prototype}`);
+            return Reflect.setPrototypeOf(target, prototype);
+        },
+        preventExtensions(target) {
+            console.log(`Preventing extensions of ${name}`);
+            return Reflect.preventExtensions(target);
+        },
+    });
+    return proxy;
+}

package/dist/utils/react.js

@@ -1,6 +1,7 @@
 import { use } from "react";
 import { neverResolve } from "./promises";
 import { deindent } from "./strings";
+import { isBrowserLike } from "./env";
 export function getNodeText(node) {
     if (["number", "string"].includes(typeof node)) {
         return `${node}`;
@@ -29,7 +30,7 @@ export function suspend() {
  * Use this in a component or a hook to disable SSR. Should be wrapped in a Suspense boundary, or it will throw an error.
  */
 export function suspendIfSsr(caller) {
-    if (typeof window === "undefined") {
+    if (!isBrowserLike()) {
         const error = Object.assign(new Error(deindent `
         ${caller ?? "This code path"} attempted to display a loading indicator during SSR by falling back to the nearest Suspense boundary. If you see this error, it means no Suspense boundary was found, and no loading indicator could be displayed. Make sure you are not catching this error with try-catch, and that the component is rendered inside a Suspense boundary, for example by adding a \`loading.tsx\` file in your app directory.
 

package/dist/utils/results.d.ts

@@ -5,11 +5,11 @@ export type Result<T, E = unknown> = {
     status: "error";
     error: E;
 };
-export type AsyncResult<T, E = unknown, P = void> = Result<T, E> | {
+export type AsyncResult<T, E = unknown, P = void> = Result<T, E> | ({
     status: "pending";
 } & {
     progress: P;
-};
+});
 export declare const Result: {
     fromThrowing: typeof fromThrowing;
     fromPromise: typeof promiseToResult;
@@ -62,7 +62,7 @@ declare function promiseToResult<T>(promise: Promise<T>): Promise<Result<T>>;
 declare function fromThrowing<T>(fn: () => T): Result<T, unknown>;
 declare function mapResult<T, U, E = unknown, P = unknown>(result: Result<T, E>, fn: (data: T) => U): Result<U, E>;
 declare function mapResult<T, U, E = unknown, P = unknown>(result: AsyncResult<T, E, P>, fn: (data: T) => U): AsyncResult<U, E, P>;
-declare class RetryError extends Error {
+declare class RetryError extends AggregateError {
     readonly errors: unknown[];
     constructor(errors: unknown[]);
     get retries(): number;

package/dist/utils/results.js

@@ -1,4 +1,5 @@
 import { wait } from "./promises";
+import { deindent } from "./strings";
 export const Result = {
     fromThrowing,
     fromPromise: promiseToResult,
@@ -83,10 +84,17 @@ function mapResult(result, fn) {
         };
     return Result.ok(fn(result.data));
 }
-class RetryError extends Error {
+class RetryError extends AggregateError {
     errors;
     constructor(errors) {
-        super(`Error after retrying ${errors.length} times.`, { cause: errors[errors.length - 1] });
+        super(errors, deindent `
+      Error after retrying ${errors.length} times.
+      
+      ${errors.map((e, i) => deindent `
+        Attempt ${i + 1}:
+          ${e}
+      `).join("\n\n")}
+      `, { cause: errors[errors.length - 1] });
         this.errors = errors;
         this.name = "RetryError";
     }

package/dist/utils/stores.d.ts

@@ -1,5 +1,28 @@
 import { AsyncResult, Result } from "./results";
 import { ReactPromise } from "./promises";
+export type ReadonlyStore<T> = {
+    get(): T;
+    onChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+    onceChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+};
+export declare class Store<T> implements ReadonlyStore<T> {
+    private _value;
+    private readonly _callbacks;
+    constructor(_value: T);
+    get(): T;
+    set(value: T): void;
+    update(updater: (value: T) => T): T;
+    onChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+    onceChange(callback: (value: T, oldValue: T | undefined) => void): {
+        unsubscribe: () => void;
+    };
+}
 export type ReadonlyAsyncStore<T> = {
     isAvailable(): boolean;
     get(): AsyncResult<T, unknown, void>;

package/dist/utils/stores.js

@@ -1,6 +1,42 @@
 import { AsyncResult, Result } from "./results";
 import { generateUuid } from "./uuids";
 import { pending, rejected, resolved } from "./promises";
+export class Store {
+    _value;
+    _callbacks = new Map();
+    constructor(_value) {
+        this._value = _value;
+    }
+    get() {
+        return this._value;
+    }
+    set(value) {
+        const oldValue = this._value;
+        this._value = value;
+        this._callbacks.forEach((callback) => callback(value, oldValue));
+    }
+    update(updater) {
+        const value = updater(this._value);
+        this.set(value);
+        return value;
+    }
+    onChange(callback) {
+        const uuid = generateUuid();
+        this._callbacks.set(uuid, callback);
+        return {
+            unsubscribe: () => {
+                this._callbacks.delete(uuid);
+            },
+        };
+    }
+    onceChange(callback) {
+        const { unsubscribe } = this.onChange((...args) => {
+            unsubscribe();
+            callback(...args);
+        });
+        return { unsubscribe };
+    }
+}
 export class AsyncStore {
     _isAvailable;
     _value = undefined;

package/dist/utils/strings.d.ts

@@ -39,3 +39,6 @@ export declare function trimLines(s: string): string;
 export declare function templateIdentity(strings: TemplateStringsArray | readonly string[], ...values: any[]): string;
 export declare function deindent(code: string): string;
 export declare function deindent(strings: TemplateStringsArray | readonly string[], ...values: any[]): string;
+export declare function nicify(value: unknown, { depth }?: {
+    depth?: number | undefined;
+}): string;

package/dist/utils/strings.js

@@ -92,3 +92,49 @@ export function deindent(strings, ...values) {
     });
     return templateIdentity(deindentedStrings, ...indentedValues);
 }
+export function nicify(value, { depth = 5 } = {}) {
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+        case "number": {
+            return JSON.stringify(value);
+        }
+        case "undefined": {
+            return "undefined";
+        }
+        case "symbol": {
+            return value.toString();
+        }
+        case "bigint": {
+            return `${value}n`;
+        }
+        case "function": {
+            if (value.name)
+                return `function ${value.name}(...) { ... }`;
+            return `(...) => { ... }`;
+        }
+        case "object": {
+            if (value === null)
+                return "null";
+            if (Array.isArray(value)) {
+                if (depth <= 0 && value.length !== 0)
+                    return "[...]";
+                return `[${value.map((v) => nicify(v, { depth: depth - 1 })).join(", ")}]`;
+            }
+            const entries = Object.entries(value);
+            if (entries.length === 0)
+                return "{}";
+            if (depth <= 0)
+                return "{...}";
+            return `{ ${Object.entries(value).map(([k, v]) => {
+                if (typeof v === "function" && v.name === k)
+                    return `${k}(...): { ... }`;
+                else
+                    return `${k}: ${nicify(v, { depth: depth - 1 })}`;
+            }).join(", ")} }`;
+        }
+        default: {
+            return `${typeof value}<${value}>`;
+        }
+    }
+}

package/dist/utils/uuids.d.ts

@@ -1 +1 @@
-export declare function generateUuid(): string;
+export declare function generateUuid(): any;

package/dist/utils/uuids.js

@@ -1,3 +1,4 @@
+import { globalVar } from "./globals";
 export function generateUuid() {
-    return globalThis.crypto.randomUUID();
+    return globalVar.crypto.randomUUID();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackframe/stack-shared",
-  "version": "2.4.13",
+  "version": "2.4.20",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -26,7 +26,7 @@
     "jose": "^5.2.2",
     "oauth4webapi": "^2.10.3",
     "uuid": "^9.0.1",
-    "@stackframe/stack-sc": "1.5.6"
+    "@stackframe/stack-sc": "2.4.20"
   },
   "devDependencies": {
     "rimraf": "^5.0.5",