adds the extracted @gadgetinc/core package

Author: infiton

packages/core/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@gadgetinc/core",
+  "version": "0.1.0",
+  "files": [
+    "README.md",
+    "dist/**/*"
+  ],
+  "license": "MIT",
+  "repository": "github:gadget-inc/js-clients",
+  "homepage": "https://github.com/gadget-inc/js-clients/tree/main/packages/core",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    }
+  },
+  "source": "src/index.ts",
+  "main": "dist/cjs/index.js",
+  "sideEffects": false,
+  "scripts": {
+    "typecheck:main": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist/ *.tsbuildinfo **/*.tsbuildinfo",
+    "prebuild": "mkdir -p dist/cjs dist/esm && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json && echo '{\"type\": \"module\"}' > dist/esm/package.json",
+    "build": "pnpm clean && pnpm prebuild && tsc -b tsconfig.cjs.json tsconfig.esm.json",
+    "prepublishOnly": "pnpm build",
+    "prerelease": "gitpkg publish"
+  },
+  "dependencies": {
+    "klona": "^2.0.6"
+  },
+  "peerDependencies": {
+    "@urql/core": "*",
+    "graphql": "*",
+    "graphql-ws": "*"
+  },
+  "devDependencies": {
+    "type-fest": "^3.13.1"
+  }
+}

packages/core/src/AnyClient.ts

@@ -0,0 +1,30 @@
+import type { AnyConnection } from "./AnyConnection.js";
+import type { GadgetTransaction } from "./GadgetTransaction.js";
+import type { AnyInternalModelManager } from "./InternalModelManager.js";
+
+export const $modelRelationships = Symbol.for("gadget/modelRelationships");
+
+export type InternalModelManagerNamespace = {
+  // internal model managers can be maps of model names to model managers, subnamespaces, or utility functions
+  [key: string]: AnyInternalModelManager | InternalModelManagerNamespace | ((...args: any[]) => any);
+};
+
+/**
+ * An instance of any Gadget app's API client object
+ */
+export interface AnyClient {
+  connection: AnyConnection;
+  query(graphQL: string, variables?: Record<string, any>): Promise<any>;
+  mutate(graphQL: string, variables?: Record<string, any>): Promise<any>;
+  transaction<T>(callback: (transaction: GadgetTransaction) => Promise<T>): Promise<T>;
+  internal: InternalModelManagerNamespace;
+  apiClientCoreVersion?: string;
+  [$modelRelationships]?: { [modelName: string]: { [apiIdentifier: string]: { type: string; model: string } } };
+}
+
+/**
+ * Checks if the given object is an instance of any Gadget app's generated JS client object
+ */
+export const isGadgetClient = (client: any): client is AnyClient => {
+  return client && "connection" in client && client.connection && "endpoint" in client.connection;
+};

packages/core/src/AnyConnection.ts

@@ -0,0 +1,56 @@
+import type { Client, ClientOptions } from "@urql/core";
+import type { ClientOptions as SubscriptionClientOptions, createClient as createSubscriptionClient } from "graphql-ws";
+import type { AuthenticationModeOptions, Exchanges } from "./ClientOptions.js";
+import { GadgetTransaction } from "./GadgetTransaction.js";
+
+export interface GadgetSubscriptionClientOptions extends Partial<SubscriptionClientOptions> {
+  urlParams?: Record<string, string | null | undefined>;
+  connectionAttempts?: number;
+  connectionGlobalTimeoutMs?: number;
+}
+
+/**
+ * Represents the current strategy for authenticating with the Gadget platform.
+ * For individual users in web browsers, we authenticate using a session token stored client side, like a cookie, but with cross domain support.
+ * For server to server communication, or traceable access from the browser, we use pre shared secrets called API Keys
+ * And when within the Gadget platform itself, we use a private secret token called an Internal Auth Token. Internal Auth Tokens are managed by Gadget and should never be used by external developers.
+ **/
+export enum AuthenticationMode {
+  BrowserSession = "browser-session",
+  APIKey = "api-key",
+  Internal = "internal",
+  InternalAuthToken = "internal-auth-token",
+  Anonymous = "anonymous",
+  Custom = "custom",
+}
+
+export interface GadgetConnectionOptions {
+  endpoint: string;
+  authenticationMode?: AuthenticationModeOptions;
+  websocketsEndpoint?: string;
+  subscriptionClientOptions?: GadgetSubscriptionClientOptions;
+  websocketImplementation?: typeof globalThis.WebSocket;
+  fetchImplementation?: typeof globalThis.fetch;
+  environment?: string;
+  requestPolicy?: ClientOptions["requestPolicy"];
+  applicationId?: string;
+  baseRouteURL?: string;
+  exchanges?: Exchanges;
+  createSubscriptionClient?: typeof createSubscriptionClient;
+}
+
+export type TransactionRun<T> = (transaction: GadgetTransaction) => Promise<T>;
+
+export interface AnyConnection {
+  endpoint: string;
+  authenticationMode: AuthenticationMode;
+  createSubscriptionClient: typeof createSubscriptionClient;
+  options: GadgetConnectionOptions;
+  get currentClient(): Client;
+  transaction: {
+    <T>(options: GadgetSubscriptionClientOptions, run: TransactionRun<T>): Promise<T>;
+    <T>(run: TransactionRun<T>): Promise<T>;
+  };
+  close(): void;
+  fetch: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+}

packages/core/src/ClientOptions.ts

@@ -0,0 +1,130 @@
+import type { Exchange } from "@urql/core";
+import type { GadgetSubscriptionClientOptions } from "./AnyConnection.js";
+
+/** All the options for a Gadget client */
+export interface ClientOptions {
+  /**
+   *  The HTTP GraphQL endpoint this connection should connect to
+   **/
+  endpoint?: string;
+  /**
+   * The authentication strategy for connecting to the upstream API
+   **/
+  authenticationMode?: AuthenticationModeOptions;
+  /**
+   * The Websockets GraphQL endpoint this connection should connect to for transactional processing
+   **/
+  websocketsEndpoint?: string;
+  /**
+   * Custom options to pass along to the WS clients when creating them
+   **/
+  subscriptionClientOptions?: GadgetSubscriptionClientOptions;
+  /**
+   * The `WebSocket` constructor to use for building websockets. Defaults to `globalThis.WebSocket`.
+   **/
+  websocketImplementation?: any;
+  /**
+   * The `fetch` function to use for making HTTP requests. Defaults to `globalThis.fetch`.
+   **/
+  fetchImplementation?: typeof fetch;
+  /**
+   * Which of the Gadget application's environments this connection should connect to
+   **/
+  environment?: string;
+  /**
+   * The ID of the application. Not required -- only used for emitting telemetry
+   **/
+  applicationId?: string;
+  /**
+   * The root URL of the app's public HTTP surface. Used for building fully-qualified URLs when `api.fetch` is called with relative paths.
+   *
+   * This only needs to be passed if you are overriding the `endpoint` parameter to something that can't be used for building fully-qualified URLs from relative imports.
+   **/
+  baseRouteURL?: string;
+  /**
+   * A list of exchanges to merge into the default exchanges used by the client.
+   */
+  exchanges?: Exchanges;
+}
+
+/** Options to configure a specific browser-based authentication mode */
+export interface BrowserSessionAuthenticationModeOptions {
+  /**
+   * The initial token to set for browser authentication.
+   * This is useful when your session is initialized by some external authentication system, like OAuth.
+   */
+  initialToken?: string;
+
+  /**
+   * Configures how the authentication token is persisted. See `BrowserSessionStorageType`.
+   */
+  storageType?: BrowserSessionStorageType;
+  /**
+   * The shop ID to set shop tenant. Useful for fetching shop-specific data.
+   */
+  shopId?: string;
+}
+
+/**
+ * If using the `browserSession` authentication mode, sets how long the stored authentication information will last for for each user.
+ */
+export enum BrowserSessionStorageType {
+  /**
+   * `Durable` authentications ask the browser to keep the user's authentication information around for as long as it can, like the "Remember Me" button on a lot of webpages. Uses `window.localStorage` to store authentication tokens.
+   */
+  Durable = "Durable",
+  /**
+   * `Session` authentications ask the browser to keep the user's authentication information around for a given browser tab, and then remove it when the tab is closed. Useful for high security scenarios where authenticated sessions are sensitive and should be forgotten quickly, or where the user's identity is temporary and only needs to last a short while. Uses `window.sessionStorage` to store authentication tokens.
+   */
+  Session = "session",
+  /**
+   * `Temporary` authentications don't ask the browser to keep the user's authentication information around at all, such that refreshing the page will result in the user having no saved authentication state and likely being logged out. Useful for high security scenarios where authenticated sessions are sensitive and should be forgotten quickly.
+   */
+  Temporary = "temporary",
+}
+
+/** Describes how to authenticate an instance of the client with the Gadget platform */
+export interface AuthenticationModeOptions {
+  // Use an API key to authenticate with Gadget.
+  // Not strictly required, but without this the client might be useless depending on the app's permissions.
+  apiKey?: string;
+
+  // Use a web browser's `localStorage` or `sessionStorage` to persist authentication information.
+  // This allows the browser to have a persistent identity as the user navigates around and logs in and out.
+  browserSession?: boolean | BrowserSessionAuthenticationModeOptions;
+
+  // Use no authentication at all, and get access only to the data that the Unauthenticated backend role has access to.
+  anonymous?: true;
+
+  // @deprecated Use internal instead
+  internalAuthToken?: string;
+
+  // @private Use an internal platform auth token for authentication
+  // This is used to communicate within Gadget itself and shouldn't be used to connect to Gadget from other systems
+  internal?: {
+    authToken: string;
+    actAsSession?: boolean;
+    getSessionId?: () => Promise<string | undefined>;
+  };
+
+  // @private Use a passed custom function for managing authentication. For some fancy integrations that the API client supports, like embedded Shopify apps, we use platform native features to authenticate with the Gadget backend.
+  custom?: {
+    processFetch(input: RequestInfo | URL, init: RequestInit): Promise<void>;
+    processTransactionConnectionParams(params: Record<string, any>): Promise<void>;
+  };
+}
+
+export interface Exchanges {
+  /**
+   * Exchanges to add before all other exchanges.
+   */
+  beforeAll?: Exchange[];
+  /**
+   * Exchanges to add before any async exchanges.
+   */
+  beforeAsync?: Exchange[];
+  /**
+   * Exchanges to add after all other exchanges.
+   */
+  afterAll?: Exchange[];
+}

packages/core/src/DataHydrator.ts

@@ -0,0 +1,40 @@
+export const Hydrators = {
+  DateTime(value: string) {
+    return new Date(value);
+  },
+};
+
+export type Hydration = keyof typeof Hydrators;
+
+/** Instructions for a client to turn raw transport types (like strings) into useful client side types (like Dates). Unstable and not intended for developer use. */
+export interface HydrationPlan {
+  [key: string]: Hydration;
+}
+
+/**
+ * Utility for declaratively transforming object trees.
+ * Useful for turning API date strings into real Date objects, etc.
+ * Declarative so that the operations it peforms can be serialized.
+ */
+export class DataHydrator {
+  constructor(readonly plan: HydrationPlan) {}
+
+  apply(source: Record<string, any> | Record<string, any>[]) {
+    if (Array.isArray(source)) {
+      return source.map((object) => this.hydrateObject(object));
+    } else {
+      return this.hydrateObject(source);
+    }
+  }
+
+  private hydrateObject(object: Record<string, any>) {
+    const hydrated = { ...object };
+    for (const [key, hydrator] of Object.entries(this.plan)) {
+      const value = hydrated[key];
+      if (value != null) {
+        hydrated[key] = Hydrators[hydrator](value);
+      }
+    }
+    return hydrated;
+  }
+}