@omneedia/ssr/dist/module/createServerClient.d.ts

Use the omneedia JavaScript library in popular server-side rendering (SSR) frameworks.

import { omneediaClient } from '@omneedia/client-js';
import type { GenericSchema, OmneediaClientOptions } from '@omneedia/client-js/dist/module/lib/types';
import type { CookieOptionsWithName, CookieMethodsServer, CookieMethodsServerDeprecated } from './types';
/**
 * @deprecated Please specify `getAll` and `setAll` cookie methods instead of
 * the `get`, `set` and `remove`. These will not be supported in the next major
 * version.
 */
export declare function createServerClient<Database = any, SchemaName extends string & keyof Database = 'public' extends keyof Database ? 'public' : string & keyof Database, Schema extends GenericSchema = Database[SchemaName] extends GenericSchema ? Database[SchemaName] : any>(omneediaUrl: string, omneediaKey: string, options: OmneediaClientOptions<SchemaName> & {
    cookieOptions?: CookieOptionsWithName;
    cookies: CookieMethodsServerDeprecated;
    cookieEncoding?: 'raw' | 'base64url';
}): omneediaClient<Database, SchemaName, Schema>;
/**
 * Creates a omneedia Client for use on the server-side of a server-side
 * rendering (SSR) framework.
 *
 * There are two categories of uses for this function: use in middlewares and
 * use in pages, components or routes.
 *
 * **Use in middlewares.**
 *
 * Middlewares are functions that run before any rendering logic is executed on
 * the server-side. They typically have access to request headers (cookies) and
 * can modify both the request and response headers.
 *
 * In most SSR frameworks, to use omneedia correctly you *must set up a
 * middleware* and use this function in it.
 *
 * When using this in a middleware, the `cookie` option must be configured to
 * use both `getAll` and `setAll`. Alternatively you can use the `get`, `set`
 * and `remove` functions. The latter are deprecated **and not recommended**
 * for most use cases due to being difficult to use properly and they do not
 * cover important edge cases. In future major versions of the library, the
 * option to configure `get`, `set` and `remove` will be removed.
 *
 * **IMPORTANT:** Failing to implement `getAll` and `setAll` correctly (or the
 * deprecated `get`, `set` and `remove`) including omitting them **will cause
 * significant and difficult to debug authentication issues**. They will
 * manifest as: random logouts, early session termination, JSON parsing errors,
 * increased number of refresh token requests, or relying on garbage state.
 *
 * **Use in pages, components or routes.**
 *
 * To use omneedia features server-side rendered in pages, components or routes
 * (a.k.a. actions / APIs) you must create a client with this funciton. Not all
 * frameworks allow the ability to set cookies or response headers when pages
 * or components are rendered. In those cases you _can omit `setAll` (or the
 * deprecated `set`, `remove`) cookie option methods_. **It is strongly
 * recommended that if the ability to set cookies and response headers is
 * present, you should configure the `setAll` (or the deprecated `set` and
 * `remove`) cookie access methods.**
 *
 * **IMPORTANT:** If the ability to set cookies or response headers is not
 * available **middleware or an equivalent must be used.** Failing to do this
 * will cause significant and difficult to debug authentication issues.
 *
 * When `setAll` (or the deprecated `set`, `remove`) cookie methods are not
 * configured, the omneedia Client will emit a warning if it is used in a way
 * that requires setting cookies. If you see this warning, it usually means
 * that you are using the omneedia Client in a wrong way:
 *
 * - You should have, but did not configure a middleware client.
 * - There is a bug in your middleware function.
 * - You are using features of the omneedia Client that change the User, e.g.
 *   by calling `omneedia.auth.updateUser()` on the server.
 *
 * Please consult the latest omneedia guides for advice on how to avoid common
 * pitfalls depending on SSR framework.
 *
 * @param omneediaUrl The URL of the omneedia project.
 * @param omneediaKey The `anon` API key of the omneedia project.
 * @param options Various configuration options.
 */
export declare function createServerClient<Database = any, SchemaName extends string & keyof Database = 'public' extends keyof Database ? 'public' : string & keyof Database, Schema extends GenericSchema = Database[SchemaName] extends GenericSchema ? Database[SchemaName] : any>(omneediaUrl: string, omneediaKey: string, options: OmneediaClientOptions<SchemaName> & {
    cookieOptions?: CookieOptionsWithName;
    cookies: CookieMethodsServer;
    cookieEncoding?: 'raw' | 'base64url';
}): omneediaClient<Database, SchemaName, Schema>;