Friend invitation hooks

API at a glance

• invites.setContextProvider(() => context | Promise<context>): unsubscribe
• invites.getAccepted({ signal? }?): Promise<AcceptedGameInvite | null>
• invites.onAccepted(handler, onError?): unsubscribe
• validateInviteContext(value): InviteContext; InviteError

The platform owns the friend picker and sends; creators cannot read contact lists, choose a recipient or send notifications through these hooks.

Context is bounded JSON (4 KiB, depth 8), never room/world authorization. Preparation errors require a retry or an explicit basic-link choice.

The accepted result contains invitation ID, game slug, public inviter username/game-scoped player ID, context and timestamps. Normal launches return null; late registration works. Reopening may deliver the same ID, so deduplicate irreversible operations.

Outside the trusted game frame this API fails. Accepted reads support abort and a 20-second timeout; unsubscribe suppresses late callbacks. This source reference does not prove the matching npm/platform release is available.

Examples, policies and operational limits →

All exported symbols

• AcceptedGameInvite
• InviteContext
• InviteError
• InviteValue
• getAccepted
• invites
• onAccepted
• setContextProvider
• validateInviteContext

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 InviteValue = null | boolean | number | string | InviteValue[] | {
    [key: string]: InviteValue;
};
export type InviteContext = Record<string, InviteValue>;
export type AcceptedGameInvite = {
    id: string;
    gameSlug: string;
    from: {
        username: string;
        playerId: string;
    };
    context: InviteContext;
    createdAt: string;
    acceptedAt: string;
    expiresAt: string;
};
export declare class InviteError extends Error {
    readonly code: string;
    constructor(message: string, code?: string);
}
/** Defensive JSON copy; invite data never grants room/world authorization. */
export declare function validateInviteContext(value: unknown): InviteContext;
/** Supply fresh context when the player presses the platform's Invite button. */
export declare function setContextProvider(provider: () => InviteContext | Promise<InviteContext>): () => void;
/** Read the recipient-only invitation accepted by the host for this launch. */
export declare function getAccepted(options?: {
    signal?: AbortSignal;
}): Promise<AcceptedGameInvite | null>;
/** Late registration works; each subscription receives at most this launch's invite. */
export declare function onAccepted(handler: (invite: AcceptedGameInvite) => void | Promise<void>, onError?: (error: unknown) => void): () => void;
export declare const invites: Readonly<{
    setContextProvider: typeof setContextProvider;
    getAccepted: typeof getAccepted;
    onAccepted: typeof onAccepted;
}>;

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;