Asset loading

API at a glance

• assets.trackedFetch(input, { tracker?, assetId?, ...requestOptions }?): Promise<Response>
• assets.trackPromise(id, promise, tracker?): Promise<T>
• new AssetTracker()
• tracker.subscribe(listener): unsubscribe
• tracker.update(id, partialProgress): AggregateAssetProgress
• tracker.snapshot(): AggregateAssetProgress
• assets.defaultTracker

Consume the returned Response body to advance fetch progress. Check response.ok yourself: HTTP failures do not automatically reject fetch.

Aggregate progress uses bytes when all lengths are known and otherwise completed-asset count. Custom trackers isolate groups of loads; unsubscribe listeners when their UI is removed.

This tracks assets; it is not the private R2 storage API.

Examples, policies and operational limits →

All exported symbols

• AggregateAssetProgress
• AssetProgress
• AssetTracker
• assets
• defaultTracker
• trackPromise
• trackedFetch

Exact TypeScript API

Generated from the SDK source, including input options, return values, public types and overloads. Relative imports below are links between SDK source modules, not additional package subpaths. Only the entrypoints listed in the reference index are supported import paths.

export type AssetProgress = {
    id: string;
    loadedBytes: number;
    totalBytes: number | null;
    completed: boolean;
    failed: boolean;
};
export type AggregateAssetProgress = {
    assets: readonly AssetProgress[];
    loadedAssets: number;
    totalAssets: number;
    loadedBytes: number;
    totalBytes: number | null;
    ratio: number | null;
};
export declare class AssetTracker {
    #private;
    subscribe(listener: (progress: AggregateAssetProgress) => void): () => boolean;
    update(id: string, update: Partial<Omit<AssetProgress, 'id'>>): AggregateAssetProgress;
    snapshot(): AggregateAssetProgress;
}
export declare const defaultTracker: AssetTracker;
/** A normal fetch that reports byte progress as its response body is consumed. */
export declare function trackedFetch(input: RequestInfo | URL, init?: RequestInit & {
    tracker?: AssetTracker;
    assetId?: string;
}): Promise<Response>;
/** Lets an engine loader participate in the same aggregate progress tracker. */
export declare function trackPromise<T>(id: string, promise: Promise<T>, tracker?: AssetTracker): Promise<T>;
export declare const assets: Readonly<{
    AssetTracker: typeof AssetTracker;
    defaultTracker: AssetTracker;
    trackedFetch: typeof trackedFetch;
    trackPromise: typeof trackPromise;
}>;

export declare class GameServiceError extends Error {
    readonly status: number;
    readonly code: string;
    constructor(message: string, status?: number, code?: string);
}
export type GameServiceRequest = <T>(service: string, request: Record<string, unknown>) => Promise<T>;
export declare const requestGameService: GameServiceRequest;
/** Server-only adapter. Credentials must never be bundled into browser games. */
export declare function createGameServiceRequest(options: {
    baseUrl: string;
    token: string;
    fetch?: typeof fetch;
}): GameServiceRequest;

export declare const SDK_SOURCE: "inkwell-sdk";
export declare const SDK_VERSION: 1;
export type InkwellMessageType = "ready" | "loading.progress" | "loading.error" | "session.complete" | "analytics.track" | "assets.progress" | "player.get" | "presence.get" | "performance.sample" | "backend.connect" | "backend.fetch";
export type InkwellMessage = {
    source: typeof SDK_SOURCE;
    version: typeof SDK_VERSION;
    type: InkwellMessageType;
    payload?: Record<string, unknown>;
    sentAt: number;
};
export declare function parentOrigin(): string | null;
export declare function requestId(): string;
export declare function emit(type: InkwellMessageType, payload?: Record<string, unknown>): boolean;