@nhost/nhost-js 3.3.1 → 4.0.1

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

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

package/dist/src/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Main entry point for the Nhost JavaScript SDK.
+ *
+ * This package provides a unified client for interacting with Nhost services:
+ * - Authentication
+ * - Storage
+ * - GraphQL
+ * - Functions
+ *
+ * ## Import
+ *
+ * ```ts
+ * import { createClient } from "@nhost/nhost-js";
+ * ```
+ *
+ * ## Usage
+ *
+ * Create a client instance to interact with Nhost services:
+ *
+ * {@includeCode ./__tests__/docstrings.test.ts:11-115}
+ *
+ * @packageDocumentation
+ */
+export { createClient, createServerClient, type NhostClient, type NhostClientOptions, type NhostServerClientOptions, } from "./nhost";
+/**
+ * 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
+ */
+export declare const generateServiceUrl: (serviceType: "auth" | "storage" | "graphql" | "functions", subdomain?: string, region?: string, customUrl?: string) => string;
+//# 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,SAAS,CAAC;AAEjB;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC7B,aAAa,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,EACzD,YAAY,MAAM,EAClB,SAAS,MAAM,EACf,YAAY,MAAM,KACjB,MAQF,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,45 @@
+/**
+ * Main entry point for the Nhost JavaScript SDK.
+ *
+ * This package provides a unified client for interacting with Nhost services:
+ * - Authentication
+ * - Storage
+ * - GraphQL
+ * - Functions
+ *
+ * ## Import
+ *
+ * ```ts
+ * import { createClient } from "@nhost/nhost-js";
+ * ```
+ *
+ * ## Usage
+ *
+ * Create a client instance to interact with Nhost services:
+ *
+ * {@includeCode ./__tests__/docstrings.test.ts:11-115}
+ *
+ * @packageDocumentation
+ */
+export { createClient, createServerClient, } from "./nhost";
+/**
+ * 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
+ */
+export const generateServiceUrl = (serviceType, subdomain, region, customUrl) => {
+    if (customUrl) {
+        return customUrl;
+    }
+    else if (subdomain && region) {
+        return `https://${subdomain}.${serviceType}.${region}.nhost.run/v1`;
+    }
+    else {
+        return `https://local.${serviceType}.local.nhost.run/v1`;
+    }
+};
+//# 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,YAAY,EACZ,kBAAkB,GAInB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,WAAyD,EACzD,SAAkB,EAClB,MAAe,EACf,SAAkB,EACV,EAAE;IACV,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,CAAC;IACnB,CAAC;SAAM,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;QAC/B,OAAO,WAAW,SAAS,IAAI,WAAW,IAAI,MAAM,eAAe,CAAC;IACtE,CAAC;SAAM,CAAC;QACN,OAAO,iBAAiB,WAAW,qBAAqB,CAAC;IAC3D,CAAC;AACH,CAAC,CAAC"}

package/dist/src/nhost.d.ts

@@ -0,0 +1,301 @@
+import { type Client as AuthClient } from "./auth";
+import { type Client as FunctionsClient } from "./functions";
+import { type Client as GraphQLClient } from "./graphql";
+import { type Session, SessionStorage, type SessionStorageBackend } from "./session/";
+import { type Client as StorageClient } from "./storage";
+/**
+ * Main client class that provides unified access to all Nhost services.
+ * This class serves as the central interface for interacting with Nhost's
+ * authentication, storage, GraphQL, and serverless functions capabilities.
+ */
+export declare class NhostClient {
+    /**
+     * Authentication client providing methods for user sign-in, sign-up, and session management.
+     * Use this client to handle all authentication-related operations.
+     */
+    auth: AuthClient;
+    /**
+     * Storage client providing methods for file operations (upload, download, delete).
+     * Use this client to manage files in your Nhost storage.
+     */
+    storage: StorageClient;
+    /**
+     * GraphQL client providing methods for executing GraphQL operations against your Hasura backend.
+     * Use this client to query and mutate data in your database through GraphQL.
+     */
+    graphql: GraphQLClient;
+    /**
+     * Functions client providing methods for invoking serverless functions.
+     * Use this client to call your custom serverless functions deployed to Nhost.
+     */
+    functions: FunctionsClient;
+    /**
+     * Storage implementation used for persisting session information.
+     * This handles saving, retrieving, and managing authentication sessions across requests.
+     */
+    sessionStorage: SessionStorage;
+    /**
+     * Create a new Nhost client. This constructor is reserved for advanced use cases.
+     * For typical usage, use [createClient](#createclient) or [createServerClient](#createserverclient) instead.
+     *
+     * @param auth - Authentication client instance
+     * @param storage - Storage client instance
+     * @param graphql - GraphQL client instance
+     * @param functions - Functions client instance
+     * @param sessionStorage - Storage implementation for session persistence
+     */
+    constructor(auth: AuthClient, storage: StorageClient, graphql: GraphQLClient, functions: FunctionsClient, sessionStorage: SessionStorage);
+    /**
+     * Get the current session from storage.
+     * This method retrieves the authenticated user's session information if one exists.
+     *
+     * @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.
+     *
+     * This method can be used to proactively refresh tokens before they expire
+     * or to force a refresh when needed.
+     *
+     * @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
+     *
+     * @example
+     * ```ts
+     * // Refresh token if it's about to expire in the next 5 minutes
+     * const refreshedSession = await nhost.refreshSession(300);
+     *
+     * // Force refresh regardless of current token expiration
+     * const forcedRefresh = await nhost.refreshSession(0);
+     * ```
+     */
+    refreshSession(marginSeconds?: number): Promise<Session | null>;
+    /**
+     * Clear the session from storage.
+     *
+     * This method removes the current authentication session, effectively logging out the user.
+     * Note that this is a client-side operation and doesn't invalidate the refresh token on
+     * the server, which can be done with `nhost.auth.signOut({refreshToken: session.refreshTokenId})`.
+     * If the middle `updateSessionFromResponseMiddleware` is used, the session will be removed
+     * from the storage automatically and calling this method is not necessary.
+     *
+     * @example
+     * ```ts
+     * // Log out the user
+     * nhost.clearSession();
+     * ```
+     */
+    clearSession(): void;
+}
+/**
+ * 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;
+    /**
+     * Complete base URL for the functions service (overrides subdomain/region)
+     */
+    functionsUrl?: string;
+    /**
+     * Storage backend to use for session persistence. If not provided, the SDK will
+     * default to localStorage in the browser or memory in other environments.
+     */
+    storage?: SessionStorageBackend;
+}
+/**
+ * Creates and configures a new Nhost client instance optimized for client-side usage.
+ *
+ * This helper method instantiates a fully configured Nhost client by:
+ * - Instantiating the various service clients (auth, storage, functions and graphql)
+ * - Auto-detecting and configuring an appropriate session storage (localStorage in browsers, memory otherwise)
+ * - Setting up a sophisticated middleware chain for seamless authentication management:
+ *   - Automatically refreshing tokens before they expire
+ *   - Attaching authorization tokens to all service requests
+ *   - Updating the session storage when new tokens are received
+ *
+ * This method includes automatic session refresh middleware, making it ideal for
+ * client-side applications where long-lived sessions are expected.
+ *
+ * @param options - Configuration options for the client
+ * @returns A configured Nhost client
+ *
+ * @example
+ * ```ts
+ * // Create client using Nhost cloud default URLs
+ * const nhost = createClient({
+ *   subdomain: 'abcdefgh',
+ *   region: 'eu-central-1'
+ * });
+ *
+ * // Create client with custom service URLs
+ * const customNhost = createClient({
+ *   authUrl: 'https://auth.example.com',
+ *   storageUrl: 'https://storage.example.com',
+ *   graphqlUrl: 'https://graphql.example.com',
+ *   functionsUrl: 'https://functions.example.com'
+ * });
+ *
+ * // Create client using cookies for storing the session
+ * import { CookieStorage } from "@nhost/nhost-js/session";
+ *
+ * const nhost = createClient({
+ *   subdomain: 'abcdefgh',
+ *   region: 'eu-central-1',
+ *   storage: new CookieStorage({
+ *      secure: import.meta.env.ENVIRONMENT === 'production',
+ *   })
+ * });
+ * ```
+ */
+export declare function createClient(options?: NhostClientOptions): NhostClient;
+export interface NhostServerClientOptions extends NhostClientOptions {
+    /**
+     * Storage backend to use for session persistence in server environments.
+     * Unlike the base options, this field is required for server-side usage
+     * as the SDK cannot auto-detect an appropriate storage mechanism.
+     */
+    storage: SessionStorageBackend;
+}
+/**
+ * Creates and configures a new Nhost client instance optimized for server-side usage.
+ *
+ * This helper method instantiates a fully configured Nhost client specifically designed for:
+ * - Server components (in frameworks like Next.js or Remix)
+ * - API routes and middleware
+ * - Backend services and server-side rendering contexts
+ *
+ * Key differences from the standard client:
+ * - Requires explicit storage implementation (must be provided)
+ * - Disables automatic session refresh middleware (to prevent race conditions in server contexts)
+ * - Still attaches authorization tokens and updates session storage from responses
+ *
+ * The server client is ideal for short-lived request contexts where session tokens
+ * are passed in (like cookie-based authentication flows) and automatic refresh
+ * mechanisms could cause issues with concurrent requests.
+ *
+ * @param options - Configuration options for the server client (requires storage implementation)
+ * @returns A configured Nhost client optimized for server-side usage
+ *
+ * @example
+ * ```ts
+ * // Example with cookie storage for Next.js API route or server component
+ * import { cookies } from 'next/headers';
+ *
+ * const nhost = createServerClient({
+ *   region: process.env["NHOST_REGION"] || "local",
+ *   subdomain: process.env["NHOST_SUBDOMAIN"] || "local",
+ *   storage: {
+ *     // storage compatible with Next.js server components
+ *     get: (): Session | null => {
+ *       const s = cookieStore.get(key)?.value || null;
+ *       if (!s) {
+ *         return null;
+ *       }
+ *       const session = JSON.parse(s) as Session;
+ *       return session;
+ *     },
+ *     set: (value: Session) => {
+ *       cookieStore.set(key, JSON.stringify(value));
+ *     },
+ *     remove: () => {
+ *       cookieStore.delete(key);
+ *     },
+ *   },
+ * });
+ *
+ * // Example with cookie storage for Next.js middleware
+ * const nhost = createServerClient({
+ *   region: process.env["NHOST_REGION"] || "local",
+ *   subdomain: process.env["NHOST_SUBDOMAIN"] || "local",
+ *   storage: {
+ *     // storage compatible with Next.js middleware
+ *     get: (): Session | null => {
+ *       const raw = request.cookies.get(key)?.value || null;
+ *       if (!raw) {
+ *         return null;
+ *       }
+ *       const session = JSON.parse(raw) as Session;
+ *       return session;
+ *     },
+ *     set: (value: Session) => {
+ *       response.cookies.set({
+ *         name: key,
+ *         value: JSON.stringify(value),
+ *         path: "/",
+ *         httpOnly: false, //if set to true we can't access it in the client
+ *         secure: process.env.NODE_ENV === "production",
+ *         sameSite: "lax",
+ *         maxAge: 60 * 60 * 24 * 30, // 30 days in seconds
+ *       });
+ *     },
+ *     remove: () => {
+ *       response.cookies.delete(key);
+ *     },
+ *   },
+ * });
+ *
+ * // Example for express reading session from a cookie
+ *
+ * import express, { Request, Response } from "express";
+ * import cookieParser from "cookie-parser";
+ *
+ * app.use(cookieParser());
+ *
+ * const nhostClientFromCookies = (req: Request) => {
+ *   return createServerClient({
+ *     subdomain: "local",
+ *     region: "local",
+ *     storage: {
+ *       get: (): Session | null => {
+ *         const s = req.cookies.nhostSession || null;
+ *         if (!s) {
+ *           return null;
+ *         }
+ *         const session = JSON.parse(s) as Session;
+ *         return session;
+ *       },
+ *       set: (_value: Session) => {
+ *         throw new Error("It is easier to handle the session in the client");
+ *       },
+ *       remove: () => {
+ *         throw new Error("It is easier to handle the session in the client");
+ *       },
+ *     },
+ *   });
+ * };
+ * ```
+ */
+export declare function createServerClient(options: NhostServerClientOptions): NhostClient;
+//# sourceMappingURL=nhost.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nhost.d.ts","sourceRoot":"","sources":["../../src/nhost.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,MAAM,IAAI,UAAU,EAE1B,MAAM,QAAQ,CAAC;AAOhB,OAAO,EAEL,KAAK,MAAM,IAAI,eAAe,EAC/B,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,MAAM,IAAI,aAAa,EAC7B,MAAM,WAAW,CAAC;AACnB,OAAO,EAGL,KAAK,OAAO,EACZ,cAAc,EACd,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,KAAK,MAAM,IAAI,aAAa,EAC7B,MAAM,WAAW,CAAC;AAEnB;;;;GAIG;AACH,qBAAa,WAAW;IACtB;;;OAGG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;;OAGG;IACH,OAAO,EAAE,aAAa,CAAC;IAEvB;;;OAGG;IACH,OAAO,EAAE,aAAa,CAAC;IAEvB;;;OAGG;IACH,SAAS,EAAE,eAAe,CAAC;IAE3B;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;IAE/B;;;;;;;;;OASG;gBAED,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,eAAe,EAC1B,cAAc,EAAE,cAAc;IAShC;;;;;;;;;;;;;;;OAeG;IACH,cAAc,IAAI,OAAO,GAAG,IAAI;IAIhC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,CAAC,aAAa,SAAK,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAIjE;;;;;;;;;;;;;;OAcG;IACH,YAAY,IAAI,IAAI;CAGrB;AAED;;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;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAyD1E;AAED,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IAClE;;;;OAIG;IACH,OAAO,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,wBAAwB,GAChC,WAAW,CAwDb"}