@nhost/nhost-js 3.2.7 → 5.0.0-beta.1

package/dist/src/graphql/client.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview GraphQL client for the Nhost JavaScript SDK.
+ *
+ * This module provides functionality for executing GraphQL operations against
+ * a Hasura GraphQL API, with automatic authentication token handling.
+ */
+import type { ChainFunction } from "../fetch";
+/**
+ * Variables object for GraphQL operations.
+ * Key-value pairs of variable names and their values.
+ */
+export interface GraphQLVariables {
+    [key: string]: any;
+}
+/**
+ * GraphQL request object used for queries and mutations.
+ */
+export interface GraphQLRequest {
+    /** The GraphQL query or mutation string */
+    query: string;
+    /** Optional variables for parameterized queries */
+    variables?: GraphQLVariables;
+    /** Optional name of the operation to execute */
+    operationName?: string;
+}
+/**
+ * Represents a GraphQL error returned from the server.
+ */
+export interface GraphQLError {
+    /** Error message */
+    message: string;
+    /** Source locations in the GraphQL document where the error occurred */
+    locations?: {
+        line: number;
+        column: number;
+    }[];
+    /** Path in the query where the error occurred */
+    path?: string[];
+    /** Additional error information specific to the GraphQL implementation */
+    extensions?: any;
+}
+/**
+ * Standard GraphQL response format as defined by the GraphQL specification.
+ */
+export interface GraphQLResponse<T = any> {
+    /** The data returned from successful execution */
+    data?: T;
+    /** Array of errors if execution was unsuccessful or partially successful */
+    errors?: GraphQLError[];
+}
+/**
+ * Response wrapper for GraphQL operations with additional metadata.
+ */
+export interface FetchResponse<T = any> {
+    /** The parsed response body */
+    body: T;
+    /** HTTP status code of the response */
+    status: number;
+    /** HTTP headers from the response */
+    headers: Headers;
+}
+/**
+ * GraphQL client interface providing methods for executing queries and mutations
+ */
+export interface Client {
+    /**
+     * Execute a GraphQL query operation
+     *
+     * Queries are used to fetch data and should not modify any data on the server.
+     *
+     * @param request - GraphQL request object containing query and optional variables
+     * @param options - Additional fetch options to apply to the request
+     * @returns Promise with the GraphQL response and metadata
+     */
+    post: (request: GraphQLRequest, options?: RequestInit) => Promise<FetchResponse<GraphQLResponse>>;
+}
+/**
+ * Creates a GraphQL API client for interacting with a GraphQL endpoint.
+ *
+ * This client provides methods for executing queries and mutations against
+ * a GraphQL API, with support for middleware functions to handle authentication,
+ * error handling, and other cross-cutting concerns.
+ *
+ * @param baseURL - Base URL for the GraphQL endpoint
+ * @param chainFunctions - Array of middleware functions for the fetch chain
+ * @returns GraphQL client with query and mutation methods
+ */
+export declare const createAPIClient: (baseURL: string, chainFunctions?: ChainFunction[]) => Client;
+//# sourceMappingURL=client.d.ts.map

package/dist/src/graphql/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/graphql/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC/C,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,GAAG,CAAC;CAClB;AAED;;GAEG;AAEH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,GAAG;IACtC,kDAAkD;IAClD,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,4EAA4E;IAC5E,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;CACzB;AAED;;GAEG;AAEH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,GAAG;IACpC,+BAA+B;IAC/B,IAAI,EAAE,CAAC,CAAC;IACR,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;;;;OAQG;IACH,IAAI,EAAE,CACJ,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,WAAW,KAClB,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,EACf,iBAAgB,aAAa,EAAO,KA0C/B,MACN,CAAC"}

package/dist/src/graphql/client.js

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview GraphQL client for the Nhost JavaScript SDK.
+ *
+ * This module provides functionality for executing GraphQL operations against
+ * a Hasura GraphQL API, with automatic authentication token handling.
+ */
+import { createEnhancedFetch } from "../fetch";
+/**
+ * Creates a GraphQL API client for interacting with a GraphQL endpoint.
+ *
+ * This client provides methods for executing queries and mutations against
+ * a GraphQL API, with support for middleware functions to handle authentication,
+ * error handling, and other cross-cutting concerns.
+ *
+ * @param baseURL - Base URL for the GraphQL endpoint
+ * @param chainFunctions - Array of middleware functions for the fetch chain
+ * @returns GraphQL client with query and mutation methods
+ */
+export const createAPIClient = (baseURL, chainFunctions = []) => {
+    const enhancedFetch = createEnhancedFetch(chainFunctions);
+    const executeOperation = async (request, options) => {
+        const response = await enhancedFetch(`${baseURL}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(request),
+            ...options,
+        });
+        const body = await response.text();
+        const data = body ? JSON.parse(body) : {};
+        const resp = {
+            body: data,
+            status: response.status,
+            headers: response.headers,
+        };
+        if (data.errors) {
+            throw resp;
+        }
+        return resp;
+    };
+    const post = (request, options) => {
+        return executeOperation(request, options);
+    };
+    return {
+        post,
+    };
+};
+//# sourceMappingURL=client.js.map

package/dist/src/graphql/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/graphql/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAgF/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,OAAe,EACf,iBAAkC,EAAE,EACpC,EAAE;IACF,MAAM,aAAa,GAAG,mBAAmB,CAAC,cAAc,CAAC,CAAC;IAE1D,MAAM,gBAAgB,GAAG,KAAK,EAC5B,OAAuB,EACvB,OAAqB,EACoB,EAAE;QAC3C,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,GAAG,OAAO,EAAE,EAAE;YACjD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;aACnC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;YAC7B,GAAG,OAAO;SACX,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,MAAM,IAAI,GAAoB,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAE3D,MAAM,IAAI,GAAG;YACX,IAAI,EAAE,IAAI;YACV,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;SAC1B,CAAC;QAEF,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,CAAC;QACb,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,CACX,OAAuB,EACvB,OAAqB,EACoB,EAAE;QAC3C,OAAO,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC,CAAC;IAEF,OAAO;QACL,IAAI;KACK,CAAC;AACd,CAAC,CAAC"}

package/dist/src/graphql/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * This is the main module to interact with Nhost's GraphQL service.
+ * Typically you would use this modula via the main [Nhost client](main#createclient)
+ * but you can also use it directly if you have a specific use case.
+ *
+ * @module graphql
+ * @packageDocumentation
+ */
+export * from "./client";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/graphql/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/graphql/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,UAAU,CAAC"}

package/dist/src/graphql/index.js

@@ -0,0 +1,10 @@
+/**
+ * This is the main module to interact with Nhost's GraphQL service.
+ * Typically you would use this modula via the main [Nhost client](main#createclient)
+ * but you can also use it directly if you have a specific use case.
+ *
+ * @module graphql
+ * @packageDocumentation
+ */
+export * from "./client";
+//# sourceMappingURL=index.js.map

package/dist/src/graphql/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/graphql/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,UAAU,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Main entry point for the Nhost JavaScript SDK.
+ *
+ * This package provides a unified client for interacting with Nhost services:
+ * - Authentication
+ * - Storage
+ * - GraphQL
+ * - Functions
+ *
+ * @example
+ * You can import and use this package with:
+ *
+ * ```ts
+ * import { createClient } from "@nhost/nhost-js";
+ * ```
+ *
+ * and use it like:
+ *
+ * {@includeCode ./__tests__/docstrings.test.ts#mainExample}
+ *
+ * ## Error handling
+ *
+ * The SDK will throw errors on most operations if the request returns a non-2xx status code or
+ * if the request fails entirely (i.e., due to network errors). A continuation you can see
+ * how you can handle errors thrown by the SDK.
+ *
+ * ### Auth
+ *
+ * {@includeCode ./__tests__/docstrings-auth.test.ts#errorHandling}
+ *
+ * ### Storage
+ *
+ * {@includeCode ./__tests__/docstrings-storage.test.ts#errorHandling}
+ *
+ * ### GraphQL
+ *
+ * {@includeCode ./__tests__/docstrings-graphql.test.ts#errorHandling}
+ *
+ * @packageDocumentation
+ */
+import { createAPIClient as createAuthClient, type Session } from "./auth";
+import { createAPIClient as createStorageClient } from "./storage";
+import { createAPIClient as createGraphQLClient } from "./graphql";
+import { type SessionStorageInterface } from "./sessionStorage";
+export { type SessionStorageInterface, DEFAULT_SESSION_KEY, LocalStorage, MemoryStorage, CookieStorage, } from "./sessionStorage";
+export { type SessionRefreshOptions, createSessionRefreshMiddleware, } from "./middlewareRefreshSession";
+export { createAttachAccessTokenMiddleware } from "./middlewareAttachToken";
+export { createSessionResponseMiddleware } from "./middlewareResponseSession";
+/**
+ * Generates a base URL for a Nhost service based on configuration
+ *
+ * @param serviceType - Type of service (auth, storage, graphql, functions)
+ * @param subdomain - Nhost project subdomain
+ * @param region - Nhost region
+ * @param customUrl - Custom URL override if provided
+ * @returns The base URL for the service
+ *
+ * @internal
+ */
+export declare const generateServiceUrl: (serviceType: "auth" | "storage" | "graphql" | "functions", subdomain?: string, region?: string, customUrl?: string) => string;
+/**
+ * Configuration options for creating an Nhost client
+ */
+export interface NhostClientOptions {
+    /**
+     * Nhost project subdomain (e.g., 'abcdefgh'). Used to construct the base URL for services for the Nhost cloud.
+     */
+    subdomain?: string;
+    /**
+     * Nhost region (e.g., 'eu-central-1'). Used to construct the base URL for services for the Nhost cloud.
+     */
+    region?: string;
+    /**
+     * Complete base URL for the auth service (overrides subdomain/region)
+     */
+    authUrl?: string;
+    /**
+     * Complete base URL for the storage service (overrides subdomain/region)
+     */
+    storageUrl?: string;
+    /**
+     * Complete base URL for the GraphQL service (overrides subdomain/region)
+     */
+    graphqlUrl?: string;
+    /**
+     * Storage implementation to use for session persistence. If not provided, the SDK will
+     * default to localStorage in the browser or memory in other environments.
+     */
+    storage?: SessionStorageInterface;
+    /**
+     * Disable automatic session refresh. If set to true, the SDK will not attempt to refresh
+     */
+    disableAutoRefreshToken?: boolean;
+}
+/**
+ * Main client class that provides access to all Nhost services
+ */
+export declare class NhostClient {
+    /**
+     * Authentication client providing methods for user sign-in, sign-up, and session management
+     */
+    auth: ReturnType<typeof createAuthClient>;
+    /**
+     * Storage client providing methods for file operations (upload, download, delete)
+     */
+    storage: ReturnType<typeof createStorageClient>;
+    /**
+     * GraphQL client providing methods for executing GraphQL operations against your Hasura backend
+     */
+    graphql: ReturnType<typeof createGraphQLClient>;
+    /**
+     * Storage implementation used for persisting session information
+     */
+    sessionStorage: SessionStorageInterface;
+    /**
+     * Create a new Nhost client. This constructor is reserved for advanced use cases.
+     * For typical usage, use [createClient](#createclient) instead.
+     *
+     * @param auth - Authentication client
+     * @param storage - Storage client
+     * @param graphql - GraphQL client
+     * @param sessionStorage - Storage implementation for session persistence
+     */
+    constructor(auth: ReturnType<typeof createAuthClient>, storage: ReturnType<typeof createStorageClient>, graphql: ReturnType<typeof createGraphQLClient>, sessionStorage: SessionStorageInterface);
+    /**
+     * Get the current session from storage
+     *
+     * @returns The current session or null if no session exists
+     *
+     * @example
+     * ```ts
+     * const session = nhost.getUserSession();
+     * if (session) {
+     *   console.log('User is authenticated:', session.user.id);
+     * } else {
+     *   console.log('No active session');
+     * }
+     * ```
+     */
+    getUserSession(): Session | null;
+    /**
+     * Refresh the session using the current refresh token
+     * in the storage and update the storage with the new session.
+     * @param marginSeconds - The number of seconds before the token expiration to refresh the session. If the token is still valid for this duration, it will not be refreshed. Set to 0 to force the refresh.
+     *
+     * @returns The new session or null if there is currently no session or if refresh fails
+     */
+    refreshSession(marginSeconds?: number): Promise<Session | null>;
+    private _refreshSession;
+    /**
+     * Clear the session from storage
+     */
+    clearSession(): Promise<void>;
+}
+/**
+ * Creates and configures a new Nhost client instance.
+ *
+ * This helper method instantiates a fully configured Nhost client by:
+ * - Instantiating the various service clients (auth, storage, functions and graphql)
+ * - Configuring a session storage if none is provided
+ * - Setting up the necessary middleware for automatic session management:
+ *   - Automatically attaching the authorization token to requests
+ *   - Refreshing the session when it expires
+ *
+ * @param options - Configuration options for the client
+ * @returns A configured Nhost client
+ */
+export declare function createClient(options?: NhostClientOptions): NhostClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EACL,eAAe,IAAI,gBAAgB,EACnC,KAAK,OAAO,EAGb,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,IAAI,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,eAAe,IAAI,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,KAAK,uBAAuB,EAAiB,MAAM,kBAAkB,CAAC;AAQ/E,OAAO,EACL,KAAK,uBAAuB,EAC5B,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,aAAa,GACd,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,KAAK,qBAAqB,EAC1B,8BAA8B,GAC/B,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,iCAAiC,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAE,+BAA+B,EAAE,MAAM,6BAA6B,CAAC;AAE9E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAC7B,aAAa,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,EACzD,YAAY,MAAM,EAClB,SAAS,MAAM,EACf,YAAY,MAAM,KACjB,MAUF,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAElC;;OAEG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;IAE1C;;OAEG;IACH,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;IAEhD;;OAEG;IACH,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;IAEhD;;OAEG;IACH,cAAc,EAAE,uBAAuB,CAAC;IAExC;;;;;;;;OAQG;gBAED,IAAI,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,EACzC,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,EAC/C,OAAO,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,EAC/C,cAAc,EAAE,uBAAuB;IAQzC;;;;;;;;;;;;;;OAcG;IACH,cAAc,IAAI,OAAO,GAAG,IAAI;IAIhC;;;;;;OAMG;IACG,cAAc,CAAC,aAAa,GAAE,MAAW,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;YAqB3D,eAAe;IAkC7B;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;CAGpC;AAmBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAyC1E"}

package/dist/src/index.js

@@ -0,0 +1,237 @@
+/**
+ * Main entry point for the Nhost JavaScript SDK.
+ *
+ * This package provides a unified client for interacting with Nhost services:
+ * - Authentication
+ * - Storage
+ * - GraphQL
+ * - Functions
+ *
+ * @example
+ * You can import and use this package with:
+ *
+ * ```ts
+ * import { createClient } from "@nhost/nhost-js";
+ * ```
+ *
+ * and use it like:
+ *
+ * {@includeCode ./__tests__/docstrings.test.ts#mainExample}
+ *
+ * ## Error handling
+ *
+ * The SDK will throw errors on most operations if the request returns a non-2xx status code or
+ * if the request fails entirely (i.e., due to network errors). A continuation you can see
+ * how you can handle errors thrown by the SDK.
+ *
+ * ### Auth
+ *
+ * {@includeCode ./__tests__/docstrings-auth.test.ts#errorHandling}
+ *
+ * ### Storage
+ *
+ * {@includeCode ./__tests__/docstrings-storage.test.ts#errorHandling}
+ *
+ * ### GraphQL
+ *
+ * {@includeCode ./__tests__/docstrings-graphql.test.ts#errorHandling}
+ *
+ * @packageDocumentation
+ */
+import { createAPIClient as createAuthClient, } from "./auth";
+import { createAPIClient as createStorageClient } from "./storage";
+import { createAPIClient as createGraphQLClient } from "./graphql";
+import { detectStorage } from "./sessionStorage";
+import { extractTokenExpiration, createSessionRefreshMiddleware, } from "./middlewareRefreshSession";
+import { createAttachAccessTokenMiddleware } from "./middlewareAttachToken";
+import { createSessionResponseMiddleware } from "./middlewareResponseSession";
+export { DEFAULT_SESSION_KEY, LocalStorage, MemoryStorage, CookieStorage, } from "./sessionStorage";
+export { createSessionRefreshMiddleware, } from "./middlewareRefreshSession";
+export { createAttachAccessTokenMiddleware } from "./middlewareAttachToken";
+export { createSessionResponseMiddleware } from "./middlewareResponseSession";
+/**
+ * Generates a base URL for a Nhost service based on configuration
+ *
+ * @param serviceType - Type of service (auth, storage, graphql, functions)
+ * @param subdomain - Nhost project subdomain
+ * @param region - Nhost region
+ * @param customUrl - Custom URL override if provided
+ * @returns The base URL for the service
+ *
+ * @internal
+ */
+export const generateServiceUrl = (serviceType, subdomain, region, customUrl) => {
+    if (customUrl) {
+        return customUrl;
+    }
+    else if (subdomain && region) {
+        return `https://${subdomain}.${serviceType}.${region}.nhost.run/v1`;
+    }
+    else if (subdomain) {
+        return `https://${subdomain}.${serviceType}.nhost.run/v1`;
+    }
+    else {
+        return `https://local.${serviceType}.local.nhost.run/v1`;
+    }
+};
+/**
+ * Main client class that provides access to all Nhost services
+ */
+export class NhostClient {
+    /**
+     * Authentication client providing methods for user sign-in, sign-up, and session management
+     */
+    auth;
+    /**
+     * Storage client providing methods for file operations (upload, download, delete)
+     */
+    storage;
+    /**
+     * GraphQL client providing methods for executing GraphQL operations against your Hasura backend
+     */
+    graphql;
+    /**
+     * Storage implementation used for persisting session information
+     */
+    sessionStorage;
+    /**
+     * Create a new Nhost client. This constructor is reserved for advanced use cases.
+     * For typical usage, use [createClient](#createclient) instead.
+     *
+     * @param auth - Authentication client
+     * @param storage - Storage client
+     * @param graphql - GraphQL client
+     * @param sessionStorage - Storage implementation for session persistence
+     */
+    constructor(auth, storage, graphql, sessionStorage) {
+        this.auth = auth;
+        this.storage = storage;
+        this.graphql = graphql;
+        this.sessionStorage = sessionStorage;
+    }
+    /**
+     * Get the current session from storage
+     *
+     * @returns The current session or null if no session exists
+     *
+     * @example
+     * ```ts
+     * const session = nhost.getUserSession();
+     * if (session) {
+     *   console.log('User is authenticated:', session.user.id);
+     * } else {
+     *   console.log('No active session');
+     * }
+     * ```
+     */
+    getUserSession() {
+        return this.sessionStorage.get();
+    }
+    /**
+     * Refresh the session using the current refresh token
+     * in the storage and update the storage with the new session.
+     * @param marginSeconds - The number of seconds before the token expiration to refresh the session. If the token is still valid for this duration, it will not be refreshed. Set to 0 to force the refresh.
+     *
+     * @returns The new session or null if there is currently no session or if refresh fails
+     */
+    async refreshSession(marginSeconds = 60) {
+        try {
+            return await this._refreshSession(marginSeconds);
+        }
+        catch (error) {
+            try {
+                // we retry the refresh token in case of transient error
+                // or race conditions
+                console.warn("error refreshing session, retrying:", error);
+                return await this._refreshSession(marginSeconds);
+            }
+            catch (error) {
+                const errResponse = error;
+                if (errResponse?.status === 401) {
+                    // this probably means the refresh token is invalid
+                    console.error("session probably expired");
+                    this.sessionStorage.remove();
+                }
+                return null;
+            }
+        }
+    }
+    async _refreshSession(marginSeconds = 60) {
+        const session = this.sessionStorage.get();
+        if (!session) {
+            return null;
+        }
+        const tokenExpiresAt = extractTokenExpiration(session?.accessToken || "");
+        const currentTime = Date.now();
+        const sessionExpired = tokenExpiresAt < currentTime;
+        if (tokenExpiresAt - currentTime > marginSeconds * 1000) {
+            return session; // No need to refresh
+        }
+        try {
+            const response = await this.auth.refreshToken({
+                refreshToken: session.refreshToken,
+            });
+            this.sessionStorage.set(response.body);
+            return response.body;
+        }
+        catch (error) {
+            if (!sessionExpired) {
+                // If the session is not expired, we can still use the current session
+                // so there is no need to error for now
+                return session;
+            }
+            // we throw the error so the caller can handle it
+            throw error;
+        }
+    }
+    /**
+     * Clear the session from storage
+     */
+    async clearSession() {
+        this.sessionStorage.remove();
+    }
+}
+function getMiddlewareChain(auth, storage, autoRefresh) {
+    const mwChain = [
+        createSessionResponseMiddleware(storage),
+        createAttachAccessTokenMiddleware(storage),
+    ];
+    if (autoRefresh) {
+        // we need to process this one first to make sure any following middlewares
+        // run after the session has been refreshed
+        mwChain.unshift(createSessionRefreshMiddleware(auth, storage));
+    }
+    return mwChain;
+}
+/**
+ * Creates and configures a new Nhost client instance.
+ *
+ * This helper method instantiates a fully configured Nhost client by:
+ * - Instantiating the various service clients (auth, storage, functions and graphql)
+ * - Configuring a session storage if none is provided
+ * - Setting up the necessary middleware for automatic session management:
+ *   - Automatically attaching the authorization token to requests
+ *   - Refreshing the session when it expires
+ *
+ * @param options - Configuration options for the client
+ * @returns A configured Nhost client
+ */
+export function createClient(options = {}) {
+    const { subdomain, region, authUrl, storageUrl, graphqlUrl, storage = detectStorage(), disableAutoRefreshToken = false, } = options;
+    // Determine base URLs for each service
+    const authBaseUrl = generateServiceUrl("auth", subdomain, region, authUrl);
+    const storageBaseUrl = generateServiceUrl("storage", subdomain, region, storageUrl);
+    const graphqlBaseUrl = generateServiceUrl("graphql", subdomain, region, graphqlUrl);
+    // Create auth client
+    const auth = createAuthClient(authBaseUrl);
+    const mwChain = getMiddlewareChain(auth, storage, !disableAutoRefreshToken);
+    for (const mw of mwChain) {
+        auth.pushChainFunction(mw);
+    }
+    // Create storage and graphql clients with the refresh and attach token middlewares
+    const storageClient = createStorageClient(storageBaseUrl, mwChain);
+    const graphqlClient = createGraphQLClient(graphqlBaseUrl, mwChain);
+    // Return an initialized NhostClient
+    return new NhostClient(auth, storageClient, graphqlClient, storage);
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/middlewareAttachToken.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Authorization token attachment middleware for the Nhost SDK.
+ *
+ * This module provides middleware functionality to automatically attach
+ * authorization tokens to outgoing API requests, ensuring the client
+ * is properly authenticated.
+ */
+import { type SessionStorageInterface } from "./sessionStorage";
+import { type ChainFunction } from "./fetch";
+/**
+ * Creates a fetch middleware that adds the Authorization header with the current access token.
+ *
+ * This middleware:
+ * 1. Gets the current session from storage
+ * 2. Adds the authorization header with the access token to outgoing requests
+ *
+ * This middleware should be used after the refresh middleware in the chain to
+ * ensure the most recent token is used.
+ *
+ * @param storage - Storage implementation for retrieving session data
+ * @returns A middleware function that adds Authorization headers
+ */
+export declare const createAttachAccessTokenMiddleware: (storage: SessionStorageInterface) => ChainFunction;
+//# sourceMappingURL=middlewareAttachToken.d.ts.map

package/dist/src/middlewareAttachToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middlewareAttachToken.d.ts","sourceRoot":"","sources":["../../src/middlewareAttachToken.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,SAAS,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iCAAiC,GAC5C,SAAS,uBAAuB,KAC/B,aA+BF,CAAC"}