@use-stall/types 0.2.19 → 0.3.1

package/index.d.ts

@@ -25,3 +25,4 @@ export * from "./src/connectors";
 export * from "./src/pin-auth";
 export * from "./src/integrations";
 export * from "./src/promotions";
+export * from "./src/core-sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-stall/types",
-  "version": "0.2.19",
+  "version": "0.3.1",
   "description": "Type declarations for Stall SDKs",
   "types": "index.d.ts",
   "type": "module",

package/src/core-sdk.d.ts

@@ -0,0 +1,102 @@
+import {
+  ConnectorModuleKey,
+  UnifiedProductType,
+  UnifiedOrderType,
+  UnifiedCustomerType,
+  UnifiedCollectionType,
+  UnifiedCategoryType,
+  UnifiedVariantsType,
+  UnifiedInventoryLevelType,
+  UnifiedPromotion,
+  UnifiedOrderNote,
+  UnifiedOrderRefundType,
+  UnifiedPaymentProviderType,
+  UnifiedPaymentCollectionType,
+  UnifiedTaxRate,
+  UnifiedTaxClass,
+  UnifiedLocationType,
+  UnifiedFulfillmentType,
+  UnifiedTagProductTag,
+  UnifiedFulfillmentProviderConfigType,
+  UnifiedFulfillmentMethodType,
+} from "@use-stall/types";
+
+export interface StallCoreConfigOptions {
+  connector_url: string;
+  version: string;
+  configuration: Record<string, any>;
+}
+
+export interface CoreConfig {
+  options: StallCoreConfigOptions;
+  adapter: () => Promise<AdapterModuleType>;
+  refreshAdapter: () => Promise<AdapterModuleType>;
+}
+
+type ModuleTypeMap = {
+  products: UnifiedProductType;
+  variants: UnifiedVariantsType;
+  collections: UnifiedCollectionType;
+  categories: UnifiedCategoryType;
+  tags: UnifiedTagProductTag;
+  inventory_levels: UnifiedInventoryLevelType;
+  inventory_history: UnifiedInventoryLevelType;
+  promotions: UnifiedPromotion;
+  orders: UnifiedOrderType;
+  order_notes: UnifiedOrderNote;
+  refunds: UnifiedOrderRefundType;
+  payment_providers: UnifiedPaymentProviderType;
+  payments: UnifiedPaymentCollectionType;
+  tax_rates: UnifiedTaxRate;
+  tax_classes: UnifiedTaxClass;
+  customers: UnifiedCustomerType;
+  locations: UnifiedLocationType;
+  fulfillment_types: UnifiedFulfillmentMethodType;
+  fulfillment_providers: UnifiedFulfillmentProviderConfigType;
+  fulfillments: UnifiedFulfillmentType;
+};
+
+// Extended module key that includes tax_classes
+type ExtendedModuleKey = ConnectorModuleKey | "tax_classes";
+
+type GetModuleType<K extends ExtendedModuleKey> = K extends keyof ModuleTypeMap
+  ? ModuleTypeMap[K]
+  : never;
+
+export type AdapterModuleType = {
+  [K in ExtendedModuleKey]: {
+    list: (props: {
+      connector_config: Record<string, any>;
+      query?: string;
+    }) => Promise<GetModuleType<K>[]>;
+    retrieve: (props: {
+      connector_config: Record<string, any>;
+      id: string;
+    }) => Promise<GetModuleType<K>>;
+    create: (props: {
+      connector_config: Record<string, any>;
+      data: GetModuleType<K>;
+    }) => Promise<GetModuleType<K>>;
+    update: (props: {
+      connector_config: Record<string, any>;
+      id: string;
+      data: Partial<GetModuleType<K>>;
+    }) => Promise<GetModuleType<K>>;
+    delete: (props: {
+      connector_config: Record<string, any>;
+      id: string;
+    }) => Promise<void>;
+    bulk_create: (props: {
+      connector_config: Record<string, any>;
+      data: GetModuleType<K>[];
+    }) => Promise<GetModuleType<K>[]>;
+    bulk_update: (props: {
+      connector_config: Record<string, any>;
+      data: Array<{ id: string; data: Partial<GetModuleType<K>> }>;
+    }) => Promise<GetModuleType<K>[]>;
+    bulk_delete: (props: {
+      connector_config: Record<string, any>;
+      ids: string[];
+    }) => Promise<void>;
+  };
+};

package/src/device.d.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import type { InstalledExtensionType } from "./extensions";
 import type { UnifiedFulfillmentMethods } from "./fulfillment";
 import type { UnifiedMethodsType } from "./payments";

package/src/extensions.d.ts

@@ -1,3 +1,180 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { UnifiedOrderType } from "./orders";
+import { ComponentType } from "./utils/react";
+import type { Router } from "./utils/router";
+import { LookupGroupRouteType } from "./utils/lookup";
+import type { CoreConfig } from "./core-sdk";
+
+interface StallExtension {
+  // entrypoint: {
+  //   id: string; // Can be lookup group or page id
+  //   type: "lookup" | "page";
+  // };
+  pages: ExtensionPage[];
+  lookup: ExtensionLookupGroup[];
+}
+
+interface ExtensionPage {
+  index: boolean;
+  id: string;
+  title: string;
+  description: string;
+  ui: string; // Name of the component in ui.ts
+}
+
+interface ExtensionActionShortcut {
+  modifiers: string[];
+  key: string;
+}
+
+interface ExtensionLookupAction {
+  native: boolean;
+  name: string;
+  label: string;
+  static_args: Record<string, any>;
+  close_on_complete: boolean; // Close lookup
+  reopen_on_return?: boolean; // Reopen lookup on return from an external page
+  always_show?: boolean; // Always show the action in the lookup even if no item is selected or highlighted
+  shortcut?: ExtensionActionShortcut;
+  paths?: string[]; // You can specify a list of paths where this action should be available, when left empty it will be available everywhere
+}
+
+interface ExtensionActionFunctionProps {
+  static_args: Record<string, any>;
+  item: any;
+  router: Router;
+  active_group: LookupGroupRouteType;
+  action: ExtensionLookupAction;
+}
+
+enum ListDataSourceOptions {
+  PRODUCTS = "products",
+  CUSTOMERS = "customers",
+  ORDERS = "orders",
+  PARKED_ORDERS = "parked_orders",
+  COLLECTIONS = "collections",
+  CATEGORIES = "categories",
+  REGISTERS = "register_sessions",
+  TRANSACTIONS = "session_transactions",
+}
+
+type ListKeyFormat =
+  | "string"
+  | "number"
+  | "array"
+  | "date"
+  | "price"
+  | "status"
+  | "none";
+
+type ListFormatKey = {
+  value: string;
+  format: ListKeyFormat;
+  className?: string;
+};
+
+type ListKeys = {
+  id: string;
+  image: string;
+  fallback?: string;
+  title: ListFormatKey;
+  description?: ListFormatKey;
+  right?: ListFormatKey;
+};
+
+type ListFilters = {
+  key: string;
+  type: "string" | "number" | "array";
+  query_value: string;
+  dynamic: boolean;
+};
+
+interface LocalListUIComponent {
+  id: string;
+  title: string;
+  description: string;
+  data_origin: "local";
+  filters: ListFilters[];
+  sorting: {
+    key: string;
+    order: "asc" | "desc";
+  };
+  source: ListDataSourceOptions;
+  keys: ListKeys;
+  actions: ExtensionLookupAction[];
+}
+
+interface RemoteListUIComponent {
+  id: string;
+  title: string;
+  description: string;
+  data_origin: "remote";
+  filters: ListFilters[];
+  sorting: {
+    key: string;
+    order: "asc" | "desc";
+  };
+  source: string;
+  keys: ListKeys;
+  actions: ExtensionLookupAction[];
+}
+
+type ExtensionLookupGroup = LocalListUIComponent | RemoteListUIComponent;
+
+interface UIProps {
+  item: any;
+  search_query: Record<string, string>;
+  base_currency: string;
+  active_cart: UnifiedOrderType | null;
+  BackButton: ComponentType<any>;
+  LoaderComponent: ComponentType<any>;
+  router: Router;
+  stall: CoreConfig;
+}
+
+interface StallExtensionConfig {
+  $schema: string;
+  id: string;
+  name: string;
+  description: string;
+  keywords: string[];
+  icon: string;
+  version: string;
+  authors: string[];
+  repo: string;
+  homepage: string;
+  offline_ready: boolean;
+  entrypoint: {
+    id: string;
+    type: string; //"lookup" | "page";
+  };
+}
+
+enum ExtensionNativeActions {
+  OPEN_GROUP = "open_group",
+  OPEN_PAGE = "open_page",
+  ADD_TO_CART = "add_to_cart",
+  ADD_CUSTOMER_TO_ORDER = "add_customer_to_order",
+}
+
+export type {
+  StallExtension,
+  ExtensionPage,
+  ExtensionActionShortcut,
+  ExtensionLookupAction,
+  ExtensionActionFunctionProps,
+  ListFilters,
+  ListFormatKey,
+  ListKeys,
+  LocalListUIComponent,
+  RemoteListUIComponent,
+  ExtensionLookupGroup,
+  UIProps,
+  StallExtensionConfig,
+};
+
+export { ListDataSourceOptions, ExtensionNativeActions };
+
 export interface ExtensionType {
   id: string;
   version: string;
@@ -10,8 +187,7 @@ export interface ExtensionType {
   authors: string[];
 }
 
-
 export interface InstalledExtensionType {
   id: string;
   version: string;
-}
+}

package/src/utils/lookup.d.ts

@@ -0,0 +1,17 @@
+export interface LookupGroupRouteType {
+  id: string;
+  title: string;
+  extension: {
+    id: string;
+    title: string;
+  };
+  previous_route_item: Record<string, any>;
+  filters?: LookupListFilters[];
+}
+
+export type LookupListFilters = {
+  key: string;
+  type: "string" | "number" | "array";
+  query_value: string;
+  dynamic: boolean;
+};

package/src/utils/react.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A React component — either a function component or a class component —
+ * that accepts props of type P.
+ */
+export type ComponentType<P = {}> = 
+  | ((props: P & { children?: ReactNode }) => ReactNode)
+  | (new (props: P & { children?: ReactNode }) => { render(): ReactNode });
+
+// Basic React node types to avoid any React import
+export type ReactNode =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | ReactElement
+  | ReactNode[];
+
+export interface ReactElement<P = any> {
+  type: string | ComponentType<P>;
+  props: P;
+  key: string | number | null;
+}

package/src/utils/router.d.ts

@@ -0,0 +1,637 @@
+// ─── Primitive / shared types ────────────────────────────────────────────────
+
+export type Primitive = string | number | boolean | null | undefined;
+
+/** A URL-safe path made up of its three constituent parts. */
+export interface Path {
+  /** The portion of the URL pathname before any query string. */
+  pathname: string;
+  /** The URL search string, starting with `?`. */
+  search: string;
+  /** The URL fragment identifier, starting with `#`. */
+  hash: string;
+}
+
+/** Accepted values for the `to` argument of `navigate`. */
+export type To = string | Partial<Path>;
+
+/** A fully-resolved browser Location, augmented with router-level state. */
+export interface Location extends Path {
+  /**
+   * A value of arbitrary data associated with this location.
+   */
+  state: any;
+  /**
+   * A unique string associated with this location. May be used to safely store
+   * and retrieve data in some other storage API, like `localStorage`.
+   */
+  key: string;
+}
+
+// ─── History ─────────────────────────────────────────────────────────────────
+
+export type Action = "POP" | "PUSH" | "REPLACE";
+
+export interface Update {
+  action: Action;
+  location: Location;
+  delta: number | null;
+}
+
+export interface Listener {
+  (update: Update): void;
+}
+
+// ─── Route objects ────────────────────────────────────────────────────────────
+
+export type AgnosticRouteMatch<
+  ParamsKey extends string = string,
+  RouteObjectType extends AgnosticRouteObject = AgnosticRouteObject
+> = {
+  params: Params<ParamsKey>;
+  pathname: string;
+  pathnameBase: string;
+  route: RouteObjectType;
+};
+
+export interface IndexRouteObject {
+  caseSensitive?: boolean;
+  path?: string;
+  id?: string;
+  loader?: LoaderFunction;
+  action?: ActionFunction;
+  hasErrorBoundary?: boolean;
+  shouldRevalidate?: ShouldRevalidateFunction;
+  handle?: RouteObject["handle"];
+  index: true;
+  children?: undefined;
+  element?: React.ReactNode | null;
+  hydrateFallbackElement?: React.ReactNode | null;
+  errorElement?: React.ReactNode | null;
+  Component?: React.ComponentType | null;
+  HydrateFallback?: React.ComponentType | null;
+  ErrorBoundary?: React.ComponentType | null;
+  lazy?: LazyRouteFunction<RouteObject>;
+}
+
+export interface NonIndexRouteObject {
+  caseSensitive?: boolean;
+  path?: string;
+  id?: string;
+  loader?: LoaderFunction;
+  action?: ActionFunction;
+  hasErrorBoundary?: boolean;
+  shouldRevalidate?: ShouldRevalidateFunction;
+  handle?: any;
+  index?: false;
+  children?: RouteObject[];
+  element?: React.ReactNode | null;
+  hydrateFallbackElement?: React.ReactNode | null;
+  errorElement?: React.ReactNode | null;
+  Component?: React.ComponentType | null;
+  HydrateFallback?: React.ComponentType | null;
+  ErrorBoundary?: React.ComponentType | null;
+  lazy?: LazyRouteFunction<RouteObject>;
+}
+
+export type RouteObject = IndexRouteObject | NonIndexRouteObject;
+
+/**
+ * Framework-agnostic route object — the underlying shape the router core
+ * operates on (no React-specific fields).
+ */
+export interface AgnosticRouteObject {
+  caseSensitive?: boolean;
+  children?: AgnosticRouteObject[];
+  element?: any;
+  index?: boolean;
+  path?: string;
+  id?: string;
+  loader?: LoaderFunction;
+  action?: ActionFunction;
+  hasErrorBoundary?: boolean;
+  shouldRevalidate?: ShouldRevalidateFunction;
+  handle?: any;
+  lazy?: LazyRouteFunction<AgnosticRouteObject>;
+}
+
+export interface AgnosticDataRouteObject extends AgnosticRouteObject {
+  children?: AgnosticDataRouteObject[];
+  id: string;
+}
+
+// ─── Params ──────────────────────────────────────────────────────────────────
+
+export type Params<Key extends string = string> = {
+  readonly [key in Key]: string | undefined;
+};
+
+// ─── Loader / action functions ────────────────────────────────────────────────
+
+export type LoaderFunctionArgs<Context = any> = {
+  request: Request;
+  params: Params;
+  context?: Context;
+};
+
+export type ActionFunctionArgs<Context = any> = {
+  request: Request;
+  params: Params;
+  context?: Context;
+};
+
+export interface LoaderFunction<Context = any> {
+  (args: LoaderFunctionArgs<Context>, handlerCtx?: unknown):
+    | Promise<Response>
+    | Response
+    | Promise<any>
+    | any;
+}
+
+export interface ActionFunction<Context = any> {
+  (args: ActionFunctionArgs<Context>, handlerCtx?: unknown):
+    | Promise<Response>
+    | Response
+    | Promise<any>
+    | any;
+}
+
+export interface ShouldRevalidateFunctionArgs {
+  currentUrl: URL;
+  currentParams: Params;
+  nextUrl: URL;
+  nextParams: Params;
+  formMethod?: string;
+  formAction?: string;
+  formEncType?: string;
+  text?: string;
+  formData?: FormData;
+  json?: any;
+  actionStatus?: number;
+  actionResult?: any;
+  defaultShouldRevalidate: boolean;
+}
+
+export interface ShouldRevalidateFunction {
+  (args: ShouldRevalidateFunctionArgs): boolean;
+}
+
+export type LazyRouteFunction<R extends AgnosticRouteObject> = () => Promise<
+  Omit<R, "lazy" | "id" | "index" | "children">
+>;
+
+// ─── Navigation ──────────────────────────────────────────────────────────────
+
+export type FormMethod =
+  | "get"
+  | "post"
+  | "put"
+  | "patch"
+  | "delete"
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE";
+
+export type FormEncType =
+  | "application/x-www-form-urlencoded"
+  | "multipart/form-data"
+  | "application/json"
+  | "text/plain";
+
+export type RelativeRoutingType = "route" | "path";
+
+interface NavigateOptions {
+  replace?: boolean;
+  state?: any;
+  relative?: RelativeRoutingType;
+  flushSync?: boolean;
+  viewTransition?: boolean;
+}
+
+export interface RouterNavigateOptions extends NavigateOptions {
+  fromRouteId?: string;
+  /** Submission options */
+  formMethod?: FormMethod;
+  formAction?: string;
+  formEncType?: FormEncType;
+  body?: any;
+  formData?: FormData;
+  json?: any;
+  text?: string;
+  /** Replace / unstable flags */
+  preventScrollReset?: boolean;
+}
+
+export interface RouterFetchOptions {
+  formMethod?: FormMethod;
+  formAction?: string;
+  formEncType?: FormEncType;
+  body?: any;
+  formData?: FormData;
+  json?: any;
+  text?: string;
+  preventScrollReset?: boolean;
+}
+
+// ─── Navigation state ─────────────────────────────────────────────────────────
+
+export type NavigationState =
+  | { state: "idle"; location?: undefined; formMethod?: undefined; formAction?: undefined; formEncType?: undefined; formData?: undefined; json?: undefined; text?: undefined }
+  | { state: "loading"; location: Location; formMethod?: FormMethod; formAction?: string; formEncType?: FormEncType; formData?: FormData; json?: any; text?: string }
+  | { state: "submitting"; location: Location; formMethod: FormMethod; formAction: string; formEncType: FormEncType; formData?: FormData; json?: any; text?: string };
+
+export type Navigation = NavigationState;
+
+// ─── Fetcher ─────────────────────────────────────────────────────────────────
+
+export type FetcherState =
+  | { state: "idle"; data: undefined; formMethod?: undefined; formAction?: undefined; formEncType?: undefined; formData?: undefined; json?: undefined; text?: undefined }
+  | { state: "loading"; data: undefined; formMethod?: FormMethod; formAction?: string; formEncType?: FormEncType; formData?: FormData; json?: any; text?: string }
+  | { state: "submitting"; data: undefined; formMethod: FormMethod; formAction: string; formEncType: FormEncType; formData?: FormData; json?: any; text?: string };
+
+export type Fetcher<TData = any> = (
+  | { state: "idle"; data: TData | undefined; formMethod?: undefined; formAction?: undefined; formEncType?: undefined; formData?: undefined; json?: undefined; text?: undefined }
+  | { state: "loading"; data: TData | undefined; formMethod?: FormMethod; formAction?: string; formEncType?: FormEncType; formData?: FormData; json?: any; text?: string }
+  | { state: "submitting"; data: TData | undefined; formMethod: FormMethod; formAction: string; formEncType: FormEncType; formData?: FormData; json?: any; text?: string }
+);
+
+// ─── Blocker ─────────────────────────────────────────────────────────────────
+
+export type BlockerFunction = (args: {
+  currentLocation: Location;
+  nextLocation: Location;
+  historyAction: Action;
+}) => boolean;
+
+export type Blocker =
+  | { state: "unblocked"; reset: undefined; proceed: undefined; location: undefined }
+  | { state: "blocked"; reset: () => void; proceed: () => void; location: Location }
+  | { state: "proceeding"; reset: undefined; proceed: undefined; location: Location };
+
+// ─── Revalidation ────────────────────────────────────────────────────────────
+
+export type RevalidationState = "idle" | "loading";
+
+// ─── Deferred data ───────────────────────────────────────────────────────────
+
+export interface DeferredData {
+  readonly done: boolean;
+  readonly unwrappedData: Record<string, any>;
+  subscribe(fn: (aborted: boolean, settledKey?: string) => void): boolean;
+  cancel(): void;
+  resolveData(signal: AbortSignal): Promise<boolean>;
+}
+
+// ─── Router state ─────────────────────────────────────────────────────────────
+
+export interface RouterState {
+  historyAction: Action;
+  location: Location;
+  matches: AgnosticDataRouteMatch[];
+  initialized: boolean;
+  navigation: Navigation;
+  restoreScrollPosition: number | false | null;
+  preventScrollReset: boolean;
+  revalidation: RevalidationState;
+  loaderData: RouteData;
+  actionData: RouteData | null;
+  errors: RouteData | null;
+  fetchers: Map<string, Fetcher>;
+  blockers: Map<string, Blocker>;
+}
+
+export type AgnosticDataRouteMatch = AgnosticRouteMatch<
+  string,
+  AgnosticDataRouteObject
+>;
+
+export type RouteData = {
+  [routeId: string]: any;
+};
+
+// ─── Scroll restoration ───────────────────────────────────────────────────────
+
+export type GetScrollPositionFunction = () => number;
+
+export type GetScrollRestorationKeyFunction = (
+  location: Location,
+  matches: AgnosticDataRouteMatch[]
+) => string;
+
+// ─── Future config ────────────────────────────────────────────────────────────
+
+export interface FutureConfig {
+  unstable_skipActionErrorRevalidation: boolean;
+}
+
+// ─── Router init ─────────────────────────────────────────────────────────────
+
+export interface RouterInit {
+  routes: AgnosticRouteObject[];
+  history: {
+    readonly action: Action;
+    readonly location: Location;
+    listen(listener: Listener): () => void;
+    createHref(to: To): string;
+    encodeLocation(to: To): Path;
+    push(to: To, state?: any): void;
+    replace(to: To, state?: any): void;
+    go(delta: number): void;
+    back(): void;
+    forward(): void;
+  };
+  basename?: string;
+  mapRouteProperties?: (route: AgnosticRouteObject) => Partial<AgnosticRouteObject>;
+  future?: Partial<FutureConfig>;
+  hydrationData?: {
+    loaderData?: RouteData;
+    actionData?: RouteData | null;
+    errors?: RouteData | null;
+  };
+  window?: Window;
+  dataStrategy?: DataStrategyFunction;
+  patchRoutesOnNavigation?: PatchRoutesOnNavigationFunction;
+}
+
+// ─── Data strategy ───────────────────────────────────────────────────────────
+
+export type DataStrategyMatch = AgnosticRouteMatch<string, AgnosticDataRouteObject> & {
+  shouldLoad: boolean;
+  resolve: (
+    handlerOverride?: (
+      handler: (ctx?: unknown) => DataFunctionReturnValue
+    ) => DataFunctionReturnValue
+  ) => Promise<DataStrategyResult>;
+};
+
+export type DataFunctionReturnValue =
+  | Promise<Response>
+  | Response
+  | Promise<any>
+  | any;
+
+export type DataStrategyResult =
+  | { type: "data"; result: any }
+  | { type: "error"; result: any };
+
+export interface DataStrategyFunctionArgs<Context = any> {
+  request: Request;
+  params: Params;
+  context?: Context;
+  matches: DataStrategyMatch[];
+  fetcherKey: string | null;
+}
+
+export interface DataStrategyFunction {
+  (args: DataStrategyFunctionArgs): Promise<Record<string, DataStrategyResult>>;
+}
+
+// ─── Patch routes on navigation ───────────────────────────────────────────────
+
+export interface PatchRoutesOnNavigationFunctionArgs {
+  path: string;
+  matches: AgnosticRouteMatch[];
+  patch: (routeId: string | null, children: AgnosticRouteObject[]) => void;
+  signal: AbortSignal;
+}
+
+export interface PatchRoutesOnNavigationFunction {
+  (opts: PatchRoutesOnNavigationFunctionArgs): void | Promise<void>;
+}
+
+// ─── Subscriber ──────────────────────────────────────────────────────────────
+
+export type RouterSubscriber = (
+  state: RouterState,
+  opts: { deletedFetchers: string[]; flushSync: boolean; viewTransitionOpts?: ViewTransitionOpts }
+) => void;
+
+export interface ViewTransitionOpts {
+  currentLocation: Location;
+  nextLocation: Location;
+}
+
+// ─── Router interface (original, now fully self-contained) ────────────────────
+
+export interface Router {
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Return the basename for the router
+   */
+  get basename(): RouterInit["basename"];
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Return the future config for the router
+   */
+  get future(): FutureConfig;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Return the current state of the router
+   */
+  get state(): RouterState;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Return the routes for this router instance
+   */
+  get routes(): AgnosticDataRouteObject[];
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Return the window associated with the router
+   */
+  get window(): RouterInit["window"];
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Initialize the router, including adding history listeners and kicking off
+   * initial data fetches. Returns a function to cleanup listeners and abort
+   * any in-progress loads.
+   */
+  initialize(): Router;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Subscribe to router.state updates
+   *
+   * @param fn function to call with the new state
+   */
+  subscribe(fn: RouterSubscriber): () => void;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Enable scroll restoration behavior in the router
+   *
+   * @param savedScrollPositions Object that will manage positions, in case
+   *                             it's being restored from sessionStorage
+   * @param getScrollPosition    Function to get the active Y scroll position
+   * @param getKey               Function to get the key to use for restoration
+   */
+  enableScrollRestoration(
+    savedScrollPositions: Record<string, number>,
+    getScrollPosition: GetScrollPositionFunction,
+    getKey?: GetScrollRestorationKeyFunction
+  ): () => void;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Navigate forward/backward in the history stack
+   * @param to Delta to move in the history stack
+   */
+  navigate(to: number): Promise<void>;
+
+  /**
+   * Navigate to the given path
+   * @param to Path to navigate to
+   * @param opts Navigation options (method, submission, etc.)
+   */
+  navigate(to: To | null, opts?: RouterNavigateOptions): Promise<void>;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Trigger a fetcher load/submission
+   *
+   * @param key     Fetcher key
+   * @param routeId Route that owns the fetcher
+   * @param href    href to fetch
+   * @param opts    Fetcher options, (method, submission, etc.)
+   */
+  fetch(
+    key: string,
+    routeId: string,
+    href: string | null,
+    opts?: RouterFetchOptions
+  ): void;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Trigger a revalidation of all current route loaders and fetcher loads
+   */
+  revalidate(): void;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Utility function to create an href for the given location
+   * @param location
+   */
+  createHref(location: Location | URL): string;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Utility function to URL encode a destination path according to the internal
+   * history implementation
+   * @param to
+   */
+  encodeLocation(to: To): Path;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Get/create a fetcher for the given key
+   * @param key
+   */
+  getFetcher<TData = any>(key: string): Fetcher<TData>;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Delete the fetcher for a given key
+   * @param key
+   */
+  deleteFetcher(key: string): void;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Cleanup listeners and abort any in-progress loads
+   */
+  dispose(): void;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Get a navigation blocker
+   * @param key The identifier for the blocker
+   * @param fn  The blocker function implementation
+   */
+  getBlocker(key: string, fn: BlockerFunction): Blocker;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Delete a navigation blocker
+   * @param key The identifier for the blocker
+   */
+  deleteBlocker(key: string): void;
+
+  /**
+   * @internal
+   * PRIVATE DO NOT USE
+   *
+   * Patch additional children routes into an existing parent route
+   * @param routeId  The parent route id or a callback function accepting `patch`
+   *                 to perform batch patching
+   * @param children The additional children routes
+   */
+  patchRoutes(routeId: string | null, children: AgnosticRouteObject[]): void;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * HMR needs to pass in-flight route updates to React Router
+   * TODO: Replace this with granular route update APIs (addRoute, updateRoute, deleteRoute)
+   */
+  _internalSetRoutes(routes: AgnosticRouteObject[]): void;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Internal fetch AbortControllers accessed by unit tests
+   */
+  _internalFetchControllers: Map<string, AbortController>;
+
+  /**
+   * @internal
+   * PRIVATE - DO NOT USE
+   *
+   * Internal pending DeferredData instances accessed by unit tests
+   */
+  _internalActiveDeferreds: Map<string, DeferredData>;
+}