Stoker Platform

https://github.com/outpost-software/stoker
Admin
Stoker is a platform for building realtime internal tools with multi-tenant support, offline mode...
Tokens:68,865
Snippets:653
Trust Score:2.9
Update:6 days ago
Show doc for...
Tokens:
Raw
### Start local development server with yarn start

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/README.md

Starts a local development server and opens a browser window. Most changes are reflected live without restarting the server.

```bash
yarn start
```

--------------------------------

### Install Genkit CLI

Source: https://github.com/outpost-software/stoker/blob/main/README.md

Installs the Genkit CLI globally using npm.

```bash
npm i -g genkit-cli
```

--------------------------------

### AccessFiles example configuration

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Collection Files.md

Example configuration for AccessFiles, enforcing required role assignments for Client role, metadata size and content type constraints, and custom metadata collection constraint.

```ts
{
    assignment: {
        Client: {
            required: {
                read: ["Manager", "Supervisor"],
                update: ["Manager", "Supervisor"],
                delete: ["Manager"],
            }
        }
    },
    metadata: {
        size: " <= (5 * 1024 * 1024)",
        contentType: ' in ["application/octet-stream"]',
    },
    customMetadata: {
        collection: ' == "Work_Orders"',
    },
}
```

--------------------------------

### homePage example

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Example of a homePage configuration mapping user roles to their homepage collections. The Dashboard takes precedence if the role has access.

```typescript
{
    Manager: "Projects",
    Client: "Invoices,
}
```

--------------------------------

### Install Stoker Web SDK

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Web SDK.md

Install the @stoker-platform/web-client package via npm.

```bash
npm i @stoker-platform/web-client
```

--------------------------------

### Install dependencies with yarn

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/README.md

Run this command in the project root to install all required dependencies for the Docusaurus website.

```bash
yarn
```

--------------------------------

### Install Firebase CLI

Source: https://github.com/outpost-software/stoker/blob/main/README.md

Installs the Firebase CLI globally using npm. Required for Stoker development.

```bash
npm i -g firebase-tools
```

--------------------------------

### Install Stoker CLI

Source: https://github.com/outpost-software/stoker/blob/main/README.md

Installs the Stoker CLI globally using npm.

```bash
npm i -g @stoker-platform/cli
```

--------------------------------

### Guard web and server code with sdk checks

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Wrap web-only or server-only code in `if(sdk === "web")` and `if(sdk === "node")` blocks. Install external packages via `external.packages.json` and import dynamically. Server-only blocks are stripped from the client bundle during build.

```ts
if(sdk === "web") { 
    ...your web code goes here...
}
if(sdk === "node") { 
    ...your server code goes here...
}
```

--------------------------------

### Initialize Stoker project

Source: https://github.com/outpost-software/stoker/blob/main/README.md

Initializes a new Stoker project, initializes git, and installs dependencies for both the root and functions directories.

```bash
stoker init && git init && npm i && npm --prefix functions i
```

--------------------------------

### Example project test for billing

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/Tests.md

Shows how to write a project test using fixtures from @stoker-platform/web-test. The test skips if the role lacks update access to the Invoices collection, then navigates to a record's billing page, fills a heading, saves, and verifies the save message and that pending writes are zero.

```typescript
import { expect, test, fixtureRecordId, recordPath } from "@stoker-platform/web-test"
import { roleHasOperationAccess } from "@stoker-platform/utils"

test.describe("billing", () => {
    test.beforeEach(({ role, schema }) => {
        const canEdit = roleHasOperationAccess(schema.collections.Invoices, role, "update")
        test.skip(!canEdit, `${role} cannot edit Invoices`)
    })

    test("billing details can be saved", async ({ page, role, schema, project, ui }) => {
        const collectionSchema = schema.collections.Invoices
        const recordId = await fixtureRecordId(project, collectionSchema, role)
        await page.goto(`${recordPath(collectionSchema, recordId)}/billing`)
        await expect(page.getByRole("heading", { name: "Customer Details", exact: true })).toBeVisible()
        await page.getByLabel("Heading").fill("Billing Heading")
        await page.getByRole("button", { name: "Save", exact: true }).click()
        await expect(page.getByText("Billing details saved", { exact: true })).toBeVisible()
        await expect(ui.app.root).toHaveAttribute("data-pending-writes", "0")
    })
})
```

--------------------------------

### tryPromise

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Web SDK.md

A utility to get a Stoker config value. Provide the raw config value to `configProperty`. If the value is a function or a promise, add arguments to `args`. Returns a promise with the config value.

```APIDOC
## tryPromise

### Description
A utility to get a Stoker config value. Provide the raw config value to `configProperty`. If the value is a function or a promise, add arguments to `args`. Returns a promise with the config value.

### Method
Function

### Signature
`(configProperty: any, args?: unknown[]) => Promise<any>`

### Parameters
- **configProperty** (any) - Required - The raw config value.
- **args** (unknown[]) - Optional - Arguments to pass if the config value is a function or promise.

### Returns
`Promise<any>` - A promise with the config value.
```

--------------------------------

### MetaIcon type definition and example

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Defines the shape of a meta icon object and shows an example link tag. Used for defining meta icons for the app's home page.

```typescript
type MetaIcon = {
    rel: string
    type: string
    url: string
}
```

```html
<link key="favicon" rel="icon" type="image/png" href="./favicon.ico" />
```

--------------------------------

### tryPromise

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Node SDK.md

A utility to get a Stoker config value. Provide the raw config value to configProperty. If the value is a function or a promise, add arguments to args. Returns a promise with the config value.

```APIDOC
## tryPromise

### Description
A utility to get a Stoker config value. Provide the raw config value to `configProperty`. If the value is a function or a promise, add arguments to `args`. Returns a promise with the config value.

### Signature
`(configProperty: any, args?: unknown[]) => Promise<any>`

### Parameters
- **configProperty** (any) - Required - The raw config value to resolve.
- **args** (unknown[]) - Optional - Arguments to pass if the config value is a function or a promise.

### Returns
- **Promise<any>** - A promise resolving to the config value.
```

--------------------------------

### Initialize Google Cloud CLI

Source: https://github.com/outpost-software/stoker/blob/main/README.md

Initializes the Google Cloud CLI and sets up application default credentials.

```bash
gcloud init
```

```bash
gcloud auth application-default login
```

--------------------------------

### Build static site with yarn build

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/README.md

Generates static content into the `build` directory, which can be served using any static content hosting service.

```bash
yarn build
```

--------------------------------

### Update Genkit CLI

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/Updates.md

Install the latest version of the Genkit CLI globally.

```bash
npm i -g genkit
```

--------------------------------

### getCustomizationFile

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns a collection's config. Use this to access the `custom` and `admin` properties for a collection.

```APIDOC
## getCustomizationFile

### Description
Returns a collection's config. Use this to access the `custom` and `admin` properties for a collection.

### Signature
`(collection: string, schema: CollectionsSchema) => CollectionCustomization`

### Parameters
- **collection** (string) - The collection name.
- **schema** (CollectionsSchema) - The schema for the collection.

### Returns
- **CollectionCustomization** - The collection's customization config.
```

--------------------------------

### Update Firebase CLI

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/Updates.md

Install the latest version of the Firebase CLI globally.

```bash
npm i -g firebase-tools
```

--------------------------------

### Update Stoker CLI

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/Updates.md

Install the latest version of the Stoker CLI globally.

```bash
npm i -g @stoker-platform/cli
```

--------------------------------

### postLogin

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires after the user has successfully logged in. Provides the user object and any error that occurred.

```APIDOC
## postLogin

### Description
Fires after the user has successfully logged in.

### Signature
`(user?: User, error?: unknown) => void | Promise<void>`

### Parameters
- `user` (User) - Optional - The currently logged in [Firebase User](https://firebase.google.com/docs/reference/js/auth.user).
- `error` (unknown) - Optional - Any error that occurred during login.

### Example
```ts
postLogin: (user, error) => {
  console.log('User logged in:', user?.email)
}
```
```

--------------------------------

### sendMessage

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Node SDK.md

Sends an SMS out of the system. The `to` field must be a phone number starting with `+`.

```APIDOC
## sendMessage

### Description
Sends an SMS out of the system. The `to` field must be a phone number starting with `+`.

### Signature
```ts
(to: string, body: string) => Promise<void>
```

### Parameters
- **to** (string) - Required - Phone number starting with `+`.
- **body** (string) - Required - SMS message body.

### Returns
- Promise<void> - Resolves when the SMS is sent.
```

--------------------------------

### utils.getEnv

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the .env configuration for the project.

```APIDOC
## utils.getEnv

### Description
Returns the .env configuration for the project.

### Returns
- `Record<string, string>` - The environment variables.
```

--------------------------------

### sendMessage

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Web SDK.md

Sends an SMS out of the system. The `to` field must be a phone number starting with `+`. Requires Firestore Security Rules in `firebase-rules/firestore.custom.rules`.

```APIDOC
## sendMessage

### Description
Sends an SMS out of the system. The `to` field must be a phone number starting with `+`. Requires Firestore Security Rules in `firebase-rules/firestore.custom.rules`.

### Method
Function

### Signature
`(to: string, body: string) => Promise<void>`

### Parameters
- **to** (string) - Required - The recipient phone number, must start with `+`.
- **body** (string) - Required - The SMS message body.

### Returns
`Promise<void>`
```

--------------------------------

### preLogin

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires before the user is logged in, prior to any other authentication logic being processed. You may block the sign in by returning false.

```APIDOC
## preLogin

### Description
Fires before the user is logged in, prior to any other authentication logic being processed. You may block the sign in by returning `false`.

### Signature
`(user: User) => boolean | void | Promise<boolean | void>`

### Parameters
- `user` (User) - Required - The currently logged in [Firebase User](https://firebase.google.com/docs/reference/js/auth.user).

### Return
A boolean defining whether or not the user may proceed with login.

### Example
```ts
preLogin: (user) => {
  if (user.email === 'blocked@example.com') return false
}
```
```

--------------------------------

### Using EXTERNAL_SECRETS in Write API function

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Env Files- Back End Setup.md

Add secrets to EXTERNAL_SECRETS and reference them in your custom Cloud Functions. This example shows defining secrets with defineSecret and passing them to the writeApi function via the onCall handler.

```TypeScript
const xeroId = defineSecret("XERO_ID");
const xeroSecret = defineSecret("XERO_SECRET");

stoker["writeapi"] = onCall({
    cors: true,
    consumeAppCheckToken,
    minInstances,
    secrets: [xeroId, xeroSecret],
}, (request) => {
    return writeApi(
        request,
        {xeroId, xeroSecret},
    );
});
```

--------------------------------

### sdk

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the SDK currently in use, indicating the environment (web or node).

```APIDOC
## sdk

### Description
Returns the SDK currently in use, indicating the environment (web or node).

### Returns
- `"web" | "node"` - The SDK identifier.
```

--------------------------------

### initializeStoker

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Node SDK.md

Initializes a Stoker app with the specified environment, tenant, and configuration paths. Returns Node utilities for working with the app.

```APIDOC
## initializeStoker

### Description
Initializes a Stoker app with the specified environment, tenant, and configuration paths. Returns Node utilities for working with the app.

### Method
initializeStoker

### Signature
```ts
(
    modeEnv: "development" | "production",
    tenantId: string | undefined,
    configFilePath: string,
    customizationFilesPath: string,
    gcp?: boolean
) => Promise<NodeUtilities>
```

### Parameters
- **modeEnv** (string) - Required - The environment to start the app in. Values: "development" | "production".
- **tenantId** (string | undefined) - Required - The tenant to work with. Pass `undefined` to initialize without a tenant.
- **configFilePath** (string) - Required - The path to your global config file. For example: `join(process.cwd(), "config", "main.js")`.
- **customizationFilesPath** (string) - Required - The path to your collection config files. For example: `join(process.cwd(), "config", "collections")`.
- **gcp** (boolean) - Optional - Set to `true` if the app will be running in Google Cloud Platform environment, such as a Cloud Function.

### Returns
- **Promise<NodeUtilities>** - All Node helper functions.

### Warning
Never call `initializeStoker` with a tenant at module scope in a Cloud Function. The tenant would become the default for every request handled by that instance. Always call it inside the request handler.
```

--------------------------------

### preFileAdd

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires before a file is uploaded. Return `false` to cancel the operation.

```APIDOC
## preFileAdd

### Description
Fires before a file is uploaded.

Return `false` to cancel the operation.

### Parameters
#### Request Body
- **record** (StokerRecord) - Required - The record associated with the file.
- **fullPath** (string) - Required - The full path of the file.
- **filename** (string) - Required - The filename.
- **permissions** (FilePermissions) - Required - The permissions for the file.

### Response
#### Success Response (200)
- **boolean** (boolean) - Return `false` to cancel the operation.
```

--------------------------------

### fileOptions

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Collection Files.md

Configures file upload options, including maximum image width and thumbnail display. Can be an array or a function returning an array or Promise of arrays.

```APIDOC
## fileOptions

### Description
Configures file upload options, including maximum image width and thumbnail display. Can be an array or a function returning an array or Promise of arrays.

### Type
`FileOptions[] | (() => FileOptions[] | Promise<FileOptions[]>)`

### Properties
- **maxImageWidth** (number) - Optional - The maximum width for uploaded image files. Images above this size will be downscaled.
- **thumbnails** (boolean) - Required - Set to `true` to show thumbnails for images in the files list.
```

--------------------------------

### postFileAdd

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires after a file is uploaded.

```APIDOC
## postFileAdd

### Description
Fires after a file is uploaded.

### Parameters
#### Request Body
- **record** (StokerRecord) - Required - The record associated with the file.
- **fullPath** (string) - Required - The full path of the file.
- **filename** (string) - Required - The filename.
- **permissions** (FilePermissions) - Required - The permissions for the file.

### Response
#### Success Response (200)
No return value.
```

--------------------------------

### postOperation

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires after all read and write operations.

```APIDOC
## postOperation

### Description
Fires after all read and write operations.

### Parameters
#### Request Body
- **operation** (string) - Required - "read" | "create" | "update" | "delete"
- **data** (StokerRecord) - Optional - The record data if applicable.
- **recordId** (string) - Optional - The ID of the record if applicable.
- **context** (any) - Optional - The context of the operation.
- **retry** (boolean) - Optional - Whether this is a retry.
- **originalRecord** (StokerRecord) - Optional - The original record if applicable.

### Response
#### Success Response (200)
No return value.
```

--------------------------------

### Deploy with SSH using USE_SSH=true yarn deploy

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/README.md

Deploys the website to GitHub Pages using SSH. This command builds the website and pushes to the `gh-pages` branch.

```bash
USE_SSH=true yarn deploy
```

--------------------------------

### preOperation

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires before all read and write operations. Return false to cancel the operation.

```APIDOC
## preOperation

### Description
Fires before all read and write operations. Return `false` to cancel the operation.

### Signature
```ts
({
    operation: "read" | "create" | "update" | "delete"
    data?: StokerRecord
    recordId?: string
    context?: any
    batch?: WriteBatch
    originalRecord?: StokerRecord
}) => boolean | void | Promise<boolean | void>
```

### Parameters
- `operation` (string) - Required - The type of operation: "read", "create", "update", or "delete".
- `data` (StokerRecord) - Optional - The data being written.
- `recordId` (string) - Optional - The ID of the record being operated on.
- `context` (any) - Optional - Additional context.
- `batch` (WriteBatch) - Optional - The write batch if applicable.
- `originalRecord` (StokerRecord) - Optional - The original record before update.

### Return
A boolean defining whether the operation should proceed.

### Example
```ts
preOperation: ({ operation, recordId }) => {
  if (operation === 'delete' && recordId === 'protected') return false
}
```
```

--------------------------------

### preDuplicate

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires before all duplicate operations in the Admin UI. Return `false` to cancel the operation.

```APIDOC
## preDuplicate

### Description
Fires before all duplicate operations in the Admin UI.

Return `false` to cancel the operation.

### Parameters
#### Request Body
- **data** (Partial<StokerRecord>) - Required - The partial record data being duplicated.

### Response
#### Success Response (200)
- **boolean** (boolean) - Return `false` to cancel the operation.
```

--------------------------------

### Login to Firebase

Source: https://github.com/outpost-software/stoker/blob/main/README.md

Authenticates the Firebase CLI with your Google account.

```bash
firebase login
```

--------------------------------

### preFileAdd hook signature

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Collection Files.md

Fires before a file is uploaded. Return false to cancel the operation.

```ts
({
    record: StokerRecord
    fullPath: string
    filename: string
    permissions: FilePermissions
}) => boolean | void | Promise<boolean | void>
```

--------------------------------

### getSome

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Web SDK.md

Documentation for the getSome SDK method that retrieves multiple records from the database.

```APIDOC
## getSome

### Description
Retrieve multiple records from the database.

### Method
SDK Method

### Signature
```ts
(
    path: string[],
    options?: {
        constraints?: QueryConstraint[] | [string, WhereFilterOp, unknown][]
        only?: "cache" | "server"
        relations?: {
            fields?: (string | CollectionField)[]
            depth: number
        }
        subcollections?: {
            collections?: string[]
            depth: number
            constraints?: QueryConstraint[]
            limit?: {
                number: number
                orderByField: string
                orderByDirection: "asc" | "desc"
            }
        }
        pagination?: {
            number: number
            orderByField?: string | FieldPath
            orderByDirection?: "asc" | "desc"
            startAfter?: Cursor
            endBefore?: Cursor
        }
        noEmbeddingFields?: boolean
        noComputedFields?: boolean
    }
) => Promise<{
    cursor: Cursor;
    pages: number | undefined;
    records: StokerRecord[];
}>
```

### Parameters
- `path` (string[]) - Required - The path to the collection for the records i.e. `["Clients"]`. If the records are in a subcollection, the path will look more like `["Clients", "D89X6ZQ1sclE71BfsWmv", "Sites"]`.
- `options.constraints` (QueryConstraint[] | [string, WhereFilterOp, unknown][]) - Optional - Provide Firestore where() query constraints to the query.
- `options.only` ("cache" | "server") - Optional - Only query the cache or the server.
- `options.relations` (object) - Optional - Include related records. Specify the depth to retrieve relations for. Optionally specify a subset of relation fields to retrieve.
- `options.subcollections` (object) - Optional - Include records from each record's subcollections. Optionally specify a subset of subcollections to retrieve. Optionally provide Firestore where() query constraints to apply to subcollection queries. Optionally limit the number of results and specify results sorting.
- `options.pagination` (object) - Optional - Specify a number of results per page. Optionally enable sorting of results. Optionally provide a cursor object for `startAfter` or `endBefore`.
- `options.noComputedFields` (boolean) - Optional - Exclude computed fields from the record.
- `options.noEmbeddingFields` (boolean) - Optional - Exclude embeddings fields from the record.

### Returns
- `cursor` (Cursor) - A cursor object that can be passed to `startAfter` or `endBefore` in `options.pagination` above.
- `pages` (number | undefined) - The number of pages returned.
- `records` (StokerRecord[]) - The results of the query.
```

--------------------------------

### setDialogContent

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Show a dialog.

```APIDOC
## setDialogContent

### Description
Show a dialog.

### Signature
`(dialogContent: DialogContent | null) => void`

### Parameters
- **dialogContent** (DialogContent | null) - The dialog content to display, or `null` to close.

### Type Definition
```ts
type DialogContent = {
    title: string
    description: string
    disableClose?: boolean
    buttons?: {
        label: string
        onClick: () => void | Promise<void>
    }[]
}
```
```

--------------------------------

### preload.async

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Specifies an array of collection names that have the preload cache enabled. These collections will be preloaded first, in parallel.

```APIDOC
## preload.async

### Description
An array of collection names that have the preload cache enabled. These collections will be preloaded first, in parallel.

### Type
`string[] | (() => string[] | Promise<string[]>)`

### Example
```ts
preload: {
  async: ['users', 'posts']
}
```
```

--------------------------------

### getMode

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the environment that the app is currently running in.

```APIDOC
## getMode

### Description
Returns the environment that the app is currently running in.

### Signature
`() => "development" | "production"`

### Returns
- **string** - The environment mode: `"development"` or `"production"`.
```

--------------------------------

### utils.getGlobalConfigModule

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the app's global config.

```APIDOC
## utils.getGlobalConfigModule

### Description
Returns the app's global config.

### Returns
- `GlobalConfig` - The global config object.
```

--------------------------------

### custom.serverAccess configuration

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Collection Files.md

Define additional access control using code on the server. read only runs for roles in access.serverReadOnly; create and update are only relevant if access.serverWriteOnly is true.

```ts
{
    read?: (permissions: StokerPermissions, user: UserRecord, record?: StokerRecord) => boolean | Promise<boolean>
    create?: (permissions: StokerPermissions, user: UserRecord, record: StokerRecord) => boolean | Promise<boolean>
    update?: (permissions: StokerPermissions, user: UserRecord, record: StokerRecord, originalRecord?: StokerRecord) => boolean | Promise<boolean>
}
```

--------------------------------

### utils.getSchema

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the app's schema. Optionally includes computed fields.

```APIDOC
## utils.getSchema

### Description
Returns the app's schema. Optionally includes computed fields.

### Parameters
- `includeComputedFields` (boolean) - Optional - If true, includes computed fields in the schema.

### Returns
- `CollectionsSchema` - The app's schema.
```

--------------------------------

### postWrite

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires after all write operations.

```APIDOC
## postWrite

### Description
Fires after all write operations.

### Parameters
#### Request Body
- **operation** (string) - Required - "create" | "update" | "delete"
- **data** (StokerRecord) - Required - The record data written.
- **recordId** (string) - Required - The ID of the record.
- **context** (any) - Required - The context of the operation.
- **retry** (boolean) - Optional - Whether this is a retry.
- **originalRecord** (StokerRecord) - Optional - The original record if applicable.

### Response
#### Success Response (200)
No return value.
```

--------------------------------

### postFileUpdate

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires after a file is updated.

```APIDOC
## postFileUpdate

### Description
Fires after a file is updated.

### Parameters
#### Request Body
- **record** (StokerRecord) - Required - The record associated with the file.
- **update** (object) - Required - The update object. Can be either a rename or permissions update.
  - **type** (string) - Required - "rename" or "permissions"
  - **oldPath** (string) - Optional - The old path for rename.
  - **newPath** (string) - Optional - The new path for rename.
  - **path** (string) - Optional - The path for permissions update.
  - **originalPermissions** (FilePermissions) - Optional - The original permissions for permissions update.
  - **permissions** (FilePermissions) - Optional - The new permissions for permissions update.

### Response
#### Success Response (200)
No return value.
```

--------------------------------

### initializeStoker

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Web SDK.md

Initializes a Stoker app with the provided configuration, collection files, environment variables, and optional context. Returns a boolean indicating whether a user is logged in.

```APIDOC
## initializeStoker

### Description
Initializes a Stoker app with the provided configuration, collection files, environment variables, and optional context. Returns a boolean indicating whether a user is logged in.

### Signature
```ts
(
    config: any,
    collectionFiles: any,
    envVars: Record<string, string>,
    context?: any
) => Promise<boolean>
```

### Parameters
- **config** (any) - Required - Imported global config file. For example: `await import("config/main")`
- **collectionFiles** (any) - Required - Imported collection config files. For example (Vite): `await import.meta.glob("config/collections/*", { eager: true })`
- **envVars** (Record<string, string>) - Required - Env vars. For example (Vite): `import.meta.env`
- **context** (any) - Optional - State and helper functions that will be passed to the global and collection config files.

### Returns
A boolean indicating whether a user is logged in.
```

--------------------------------

### utils.getVersionInfo

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns information about the app's current schema version.

```APIDOC
## utils.getVersionInfo

### Description
Returns information about the app's current schema version.

### Returns
- `VersionInfo | undefined` - The version information object.
```

--------------------------------

### preload.sync

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Specifies an array of collection names that have the preload cache enabled. These collections will be preloaded synchronously while the async collections also load. Collections not listed in preload.async or preload.sync will load synchronously after the collections in this list.

```APIDOC
## preload.sync

### Description
An array of collection names that have the preload cache enabled. These collections will be preloaded synchronously while the async collections also load. Collections not listed in `preload.async` or `preload.sync` will load synchronously after the collections in this list.

### Type
`string[] | (() => string[] | Promise<string[]>)`

### Example
```ts
preload: {
  sync: ['settings']
}
```
```

--------------------------------

### getVersionInfo

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns information about the app's current schema version.

```APIDOC
## getVersionInfo

### Description
Returns information about the app's current schema version.

### Signature
`() => VersionInfo | undefined`

### Returns
- **VersionInfo | undefined** - An object containing version information, or `undefined` if not available.

### Type Definition
```ts
type VersionInfo = {
    version: number
    force: boolean
    refresh: boolean
    time: Timestamp | FieldValue
    payload: unknown
}
```
```

--------------------------------

### preFileUpdate

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires before a file is updated. Return `false` to cancel the operation.

```APIDOC
## preFileUpdate

### Description
Fires before a file is updated.

Return `false` to cancel the operation.

### Parameters
#### Request Body
- **record** (StokerRecord) - Required - The record associated with the file.
- **update** (object) - Required - The update object. Can be either a rename or permissions update.
  - **type** (string) - Required - "rename" or "permissions"
  - **oldPath** (string) - Optional - The old path for rename.
  - **newPath** (string) - Optional - The new path for rename.
  - **path** (string) - Optional - The path for permissions update.
  - **originalPermissions** (FilePermissions) - Optional - The original permissions for permissions update.
  - **permissions** (FilePermissions) - Optional - The new permissions for permissions update.

### Response
#### Success Response (200)
- **boolean** (boolean) - Return `false` to cancel the operation.
```

--------------------------------

### utils.getAppCheck

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the app's main App Check instance.

```APIDOC
## utils.getAppCheck

### Description
Returns the app's main App Check instance.

### Returns
- `AppCheck` - The App Check instance.
```

--------------------------------

### preWrite

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires before all write operations. Return `false` to cancel the operation.

```APIDOC
## preWrite

### Description
Fires before all write operations.

Return `false` to cancel the operation.

### Parameters
#### Request Body
- **operation** (string) - Required - "create" | "update" | "delete"
- **data** (StokerRecord) - Required - The record data being written.
- **recordId** (string) - Required - The ID of the record.
- **context** (any) - Required - The context of the operation.
- **batch** (WriteBatch) - Optional - The write batch if applicable.
- **originalRecord** (StokerRecord) - Optional - The original record if updating.
- **permissions** (StokerPermissions) - Optional - The permissions for the operation.

### Response
#### Success Response (200)
- **boolean** (boolean) - Return `false` to cancel the operation.
```

--------------------------------

### createRecordForm

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Show the create record form for a collection.

```APIDOC
## createRecordForm

### Description
Show the create record form for a collection.

### Signature
`(collection: CollectionSchema, collectionPath: string[], record?: StokerRecord) => false | React.ReactPortal`

### Parameters
- **collection** (CollectionSchema) - The schema for the collection.
- **collectionPath** (string[]) - The path to the record's collection, for example `["Clients"]`.
- **record** (StokerRecord, optional) - Data that will be used to pre-fill the form.

### Returns
- **false | React.ReactPortal** - Returns `false` if the form cannot be shown, or a React portal.
```

--------------------------------

### preLogout

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires when the user attempts to log out. You may block the sign out by returning false.

```APIDOC
## preLogout

### Description
Fires when the user attempts to log out. You may block the sign out by returning `false`.

### Signature
`(user: User) => boolean | void | Promise<boolean | void>`

### Parameters
- `user` (User) - Required - The currently logged in [Firebase User](https://firebase.google.com/docs/reference/js/auth.user).

### Return
A boolean defining whether or not the user may proceed with sign out.

### Example
```ts
preLogout: (user) => {
  if (user.uid === 'blocked') return false
}
```
```

--------------------------------

### preRead

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires before all read operations. Provides context, refs, and flags for multiple or listener reads.

```APIDOC
## preRead

### Description
Fires before all read operations.

### Signature
```ts
({
    context: any
    refs: unknown[]
    multiple?: boolean
    listener?: boolean
}) => void | Promise<void>
```

### Parameters
- `context` (any) - Required - The context of the read operation.
- `refs` (array) - Required - The references being read.
- `multiple` (boolean) - Optional - Whether the read is for multiple records.
- `listener` (boolean) - Optional - Whether the read is a listener.

### Example
```ts
preRead: ({ refs }) => {
  console.log('Reading refs:', refs)
}
```
```

--------------------------------

### onConnectionStatusChange

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires when the app goes online / offline.

```APIDOC
## onConnectionStatusChange

### Description
Fires when the app goes online / offline.

`first` will be true for the initial value read on app startup.

### Parameters
#### Request Body
- **status** (string) - Required - "Online" | "Offline"
- **first** (boolean) - Required - Whether this is the initial value read.

### Response
#### Success Response (200)
No return value.
```

--------------------------------

### preOperation hook signature

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires before all read and write operations. Return `false` to cancel the operation.

```ts
({
    operation: "read" | "create" | "update" | "delete"
    data?: StokerRecord
    recordId?: string
    context?: any
    batch?: WriteBatch
    originalRecord?: StokerRecord
}) => boolean | void | Promise<boolean | void>
```

--------------------------------

### addRecord

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Web SDK.md

Adds a record to the database. Supports optional user credentials, custom ID, and validation callback.

```APIDOC
## addRecord

### Description
Add a record to the database.

### Signature
`(path: string[], data: Partial<StokerRecord>, options?: { user?: { password: string, passwordConfirm: string, permissions?: StokerPermissions }, id?: string, onValid?: () => void }) => Promise<StokerRecord>`

### Parameters
- **path** (string[]) - Required - The path to the collection for the record i.e. `["Clients"]`. If the record will be in a subcollection, the path will look more like `["Clients", "D89X6ZQ1sclE71BfsWmv", "Sites"]`.
- **data** (Partial<StokerRecord>) - Required - The record to save.
- **options.user** (object) - Optional - User credentials if this collection has `auth` enabled. Contains `password`, `passwordConfirm`, and optional `permissions`.
- **options.user.permissions** (StokerPermissions) - Optional - Permissions structure as defined below.
- **options.id** (string) - Optional - Optionally provide a Firestore id for the new record.
- **options.onValid** (function) - Optional - A callback that will fire when the record has passed validation.

### StokerPermissions Type
```ts
type StokerPermissions = {
    Role?: string
    Enabled?: boolean
    collections?: {
        [collection: string]: {
            auth?: boolean
            operations: ("Read" | "Create" | "Update" | "Delete")[]
            recordOwner?: {
                active: boolean
            }
            recordUser?: {
                active: boolean
            }
            recordProperty?: {
                active: boolean
            }
            restrictEntities?: boolean
            individualEntities?: string[]
            parentEntities?: string[]
            parentPropertyEntities?: Record<string, string[]>
        }
    }
}
```

### Returns
The saved record.
```

--------------------------------

### getOne

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Web SDK.md

Retrieves a record from the database with optional relations, subcollections, and field exclusions.

```APIDOC
## getOne

### Description
Retrieves a record from the database.

### Method
GET

### Endpoint
`getOne(path, recordId, options?)`

### Parameters
#### Path Parameters
- `path` (string[]) - Required - The path to the collection for the record, e.g., `["Clients"]`. For subcollections, include the parent record ID, e.g., `["Clients", "D89X6ZQ1sclE71BfsWmv", "Sites"]`.
- `recordId` (string) - Required - The ID of the record to retrieve.

#### Query Parameters
- `options.only` ("cache" | "server") - Optional - Only query the cache or the server.
- `options.relations` (object) - Optional - Include related records. Specify the depth to retrieve relations for. Optionally specify a subset of relation fields to retrieve.
  - `fields` (string[] | CollectionField[]) - Optional - Subset of relation fields to retrieve.
  - `depth` (number) - Required - Depth to retrieve relations.
- `options.subcollections` (object) - Optional - Include records from the record's subcollections. Optionally specify a subset of subcollections to retrieve. Optionally provide Firestore where() query constraints to apply to subcollection queries. Optionally limit the number of results and specify results sorting.
  - `collections` (string[]) - Optional - Subset of subcollections to retrieve.
  - `depth` (number) - Required - Depth to retrieve subcollections.
  - `constraints` (QueryConstraint[]) - Optional - Firestore where() query constraints.
  - `limit` (object) - Optional - Limit the number of results and specify sorting.
    - `number` (number) - Required - Maximum number of results.
    - `orderByField` (string) - Required - Field to order by.
    - `orderByDirection` ("asc" | "desc") - Required - Sort direction.
- `options.noComputedFields` (boolean) - Optional - Exclude computed fields from the record.
- `options.noEmbeddingFields` (boolean) - Optional - Exclude embedding fields from the record.

### Returns
The record.
```

--------------------------------

### onVersionUpdate

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires when the schema version is updated.

```APIDOC
## onVersionUpdate

### Description
Fires when the schema version is updated.

:::warning
If `refresh` is `true` for the schema update, the page will automatically refresh and this hook will not fire.
:::

### Parameters
#### Request Body
- **versionInfo** (object) - Required - Information about the version update.
  - **version** (number) - Required - The new version number.
  - **force** (boolean) - Required - Whether the update is forced.
  - **refresh** (boolean) - Required - Whether the page will refresh.
  - **time** (Timestamp | FieldValue) - Required - The time of the update.
  - **payload** (unknown) - Required - The payload of the update.
- **numberOfUpdates** (number) - Required - The number of updates.

### Response
#### Success Response (200)
No return value.
```

--------------------------------

### initializeStoker function signature

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Node SDK.md

Initializes a Stoker app. Pass undefined for tenantId to initialize without a tenant. Set gcp to true for Google Cloud Platform environments. Never call with a tenant at module scope in a Cloud Function.

```typescript
(
    modeEnv: "development" | "production",
    tenantId: string | undefined,
    configFilePath: string,
    customizationFilesPath: string,
    gcp?: boolean
) => Promise<NodeUtilities>
```

--------------------------------

### utils.getStokerFirestore

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the app's main Firestore instance.

```APIDOC
## utils.getStokerFirestore

### Description
Returns the app's main Firestore instance.

### Returns
- `Firestore` - The main Firestore instance.
```

--------------------------------

### postRead

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Global Config File.md

Fires after all read operations.

```APIDOC
## postRead

### Description
Fires after all read operations.

### Parameters
#### Request Body
- **context** (any) - Required - The context of the operation.
- **refs** (unknown[]) - Required - The references involved.
- **record** (StokerRecord | undefined) - Required - The record read, if any.
- **listener** (boolean) - Optional - Whether this is a listener.

### Response
#### Success Response (200)
No return value.
```

--------------------------------

### postWrite hook signature

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Collection Files.md

Fires after a write operation.

```ts
({
    operation: "create" | "update" | "delete"
    data: StokerRecord
    recordId: string
    context: any
    retry?: boolean
    originalRecord?: StokerRecord
}) => void | Promise<void>
```

--------------------------------

### subscribeOne

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Web SDK.md

Documentation for the subscribeOne method, which adds a listener to a single record in the database.

```APIDOC
## subscribeOne

### Description
Adds a listener to a single record in the database. The callback fires whenever the record or its relations are updated.

### Method
subscribeOne

### Signature
```ts
(
    path: string[],
    recordId: string,
    callback: (record: StokerRecord | undefined) => void,
    errorCallback?: (error: Error) => void,
    options?: {
        only?: "cache" | "default";
        relations?: boolean | {
            fields: (string | CollectionField)[];
        };
        noComputedFields?: boolean;
        noEmbeddingFields?: boolean;
    }
) => Promise<() => void>
```

### Parameters
- `path` (string[]) - Required - The path to the collection for the record, e.g. `["Clients"]` or `["Clients", "D89X6ZQ1sclE71BfsWmv", "Sites"]` for subcollections.
- `recordId` (string) - Required - The id of the record to retrieve.
- `callback` (function) - Required - Fires whenever the record or its relations are updated in the database.
- `errorCallback` (function) - Optional - Fires whenever the listener throws an error.
- `options.only` (string) - Optional - Only query the cache, or both the cache and the server (default).
- `options.relations` (boolean | object) - Optional - Include related records. Optionally specify a subset of relation fields to retrieve.
- `options.noComputedFields` (boolean) - Optional - Exclude computed fields from the record.
- `options.noEmbeddingFields` (boolean) - Optional - Exclude embedding fields from the record.

### Returns
- `Promise<() => void>` - An unsubscribe function.
```

--------------------------------

### getGlobalConfigModule

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the app's global config.

```APIDOC
## getGlobalConfigModule

### Description
Returns the app's global config.

### Signature
`() => GlobalConfig`

### Returns
- **GlobalConfig** - The global configuration object.
```

--------------------------------

### preDuplicate hook signature

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Collection Files.md

Fires before a duplicate operation in the Admin UI. Return false to cancel the operation.

```ts
({ data: Partial<StokerRecord> }) => boolean | void | Promise<boolean | void>
```

--------------------------------

### utils.getTenant

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the tenant ID for the currently active tenant.

```APIDOC
## utils.getTenant

### Description
Returns the tenant ID for the currently active tenant.

### Returns
- `string` - The tenant ID.
```

--------------------------------

### utils.getCollectionConfigModule

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns a collection's config, including custom and admin properties.

```APIDOC
## utils.getCollectionConfigModule

### Description
Returns a collection's config, including custom and admin properties.

### Parameters
- `collection` (string) - Required - The name of the collection.

### Returns
- `CollectionCustomization` - The collection's config.
```

--------------------------------

### Deploy without SSH using GIT_USER yarn deploy

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/README.md

Deploys the website to GitHub Pages without SSH, requiring a GitHub username. This command builds the website and pushes to the `gh-pages` branch.

```bash
GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### utils.getLoadingState

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the loading state for collections with preload cache enabled.

```APIDOC
## utils.getLoadingState

### Description
Returns the loading state for collections with preload cache enabled.

### Returns
- `{ [collection: string]: "Loading" | "Loaded" | "Error" }` - The loading state map.
```

--------------------------------

### getStokerFirestore

Source: https://github.com/outpost-software/stoker/blob/main/apps/docs/docs/api-reference/Application State.md

Returns the app's main Firestore instance.

```APIDOC
## getStokerFirestore

### Description
Returns the app's main Firestore instance.

### Signature
`() => Firestore`

### Returns
- **Firestore** - The Firestore instance.
```
Tokens:
Raw