========================
CODE SNIPPETS
========================
TITLE: Install PocketBase JS SDK in Node.js (npm)
DESCRIPTION: Provides the npm command to install the PocketBase JavaScript SDK for Node.js projects, saving it as a dependency.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_2

LANGUAGE: Shell
CODE:
```
npm install pocketbase --save
```

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

TITLE: Add Fetch Polyfill for Node.js < 17
DESCRIPTION: Instructions for installing and importing a `fetch()` polyfill, like `cross-fetch`, which is necessary for PocketBase SDK functionality in Node.js versions older than 17.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_4

LANGUAGE: JavaScript
CODE:
```
// npm install cross-fetch --save
import 'cross-fetch/polyfill';
```

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

TITLE: Install PocketBase JS SDK in Browser (UMD)
DESCRIPTION: Demonstrates how to include the PocketBase JavaScript SDK in a web page using a <script> tag for UMD builds, making the PocketBase object globally available.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_0

LANGUAGE: HTML
CODE:
```
<script src="/path/to/dist/pocketbase.umd.js"></script>
<script type="text/javascript">
    const pb = new PocketBase("https://example.com")
    ...
</script>
```

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

TITLE: Add EventSource Polyfill for Node.js Realtime Subscriptions
DESCRIPTION: Guidance on installing and configuring an `EventSource` polyfill for Node.js or React Native, enabling realtime subscriptions with PocketBase as Node.js lacks native `EventSource`.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_5

LANGUAGE: JavaScript
CODE:
```
// for server: npm install eventsource --save
import { EventSource } from "eventsource";

// for React Native: npm install react-native-sse --save
import EventSource from "react-native-sse";

global.EventSource = EventSource;
```

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

TITLE: Install PocketBase JS SDK in Browser (ES Module)
DESCRIPTION: Shows how to import the PocketBase JavaScript SDK as an ES module in a browser environment using a <script type="module"> tag.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_1

LANGUAGE: HTML
CODE:
```
<script type="module">
    import PocketBase from '/path/to/dist/pocketbase.es.mjs'

    const pb = new PocketBase("https://example.com")
    ...
</script>
```

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

TITLE: Integrate PocketBase with Next.js getServerSideProps
DESCRIPTION: This example provides a helper function to initialize a PocketBase client for Next.js `getServerSideProps`. It handles loading authentication state from request cookies, updating response cookies, and refreshing authentication tokens, enabling server-side data fetching with PocketBase.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_34

LANGUAGE: JavaScript
CODE:
```
import PocketBase from 'pocketbase';

// you can place this helper in a separate file so that it can be reused
async function initPocketBase(req, res) {
  const pb = new PocketBase('http://127.0.0.1:8090');

  // load the store data from the request cookie string
  pb.authStore.loadFromCookie(req?.headers?.cookie || '');

  // send back the default 'pb_auth' cookie to the client with the latest store state
  pb.authStore.onChange(() => {
    res?.setHeader('set-cookie', pb.authStore.exportToCookie());
  });

  try {
      // get an up-to-date auth store state by verifying and refreshing the loaded auth record (if any)
      pb.authStore.isValid && await pb.collection('users').authRefresh();
  } catch (_) {
      // clear the auth store on failed refresh
      pb.authStore.clear();
  }

  return pb
}

export async function getServerSideProps({ req, res }) {
  const pb = await initPocketBase(req, res)

  // fetch example records...
  const result = await pb.collection('example').getList(1, 30);

  return {
    props: {
      // ...
    },
  }
}

export default function Home() {
  return (
    <div>Hello world!</div>
  )
}
```

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

TITLE: Fetch Data with PocketBase in Nuxt 3 Component
DESCRIPTION: This Nuxt 3 component example shows how to access the PocketBase client provided by a plugin and use `useAsyncData` to fetch a list of records from a PocketBase collection during server-side rendering.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_31

LANGUAGE: HTML
CODE:
```
<template>
  <div>
    Show: {{ data }}
  </div>
</template>

<script setup>
  const { data } = await useAsyncData(async (nuxtApp) => {
    // fetch and return all "example" records...
    const records = await nuxtApp.$pb.collection('example').getFullList();

    return structuredClone(records);
  })
</script>
```

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

TITLE: Initialize PocketBase with AsyncAuthStore for React Native
DESCRIPTION: Shows how to configure the PocketBase JS SDK to use `AsyncAuthStore` with `AsyncStorage` from React Native. This setup enables persistent authentication across app sessions by leveraging an asynchronous storage mechanism.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_12

LANGUAGE: js
CODE:
```
import AsyncStorage from '@react-native-async-storage/async-storage';
import PocketBase, { AsyncAuthStore } from 'pocketbase';

const store = new AsyncAuthStore({
    save:    async (serialized) => AsyncStorage.setItem('pb_auth', serialized),
    initial: AsyncStorage.getItem('pb_auth'),
});

const pb = new PocketBase('http://127.0.0.1:8090', store)
```

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

TITLE: Fetch Data with PocketBase in Nuxt 2 Component
DESCRIPTION: This Nuxt 2 component example demonstrates how to access the injected PocketBase client within the `asyncData` method to fetch a list of records from a PocketBase collection during server-side rendering.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_33

LANGUAGE: HTML
CODE:
```
<template>
  <div>
    Show: {{ items }}
  </div>
</template>

<script>
  export default {
    async asyncData({ $pocketbase }) {
      // fetch and return all "example" records...
      const items = await $pocketbase.collection('example').getFullList();

      return { items }
    }
  }
</script>
```

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

TITLE: PocketBase RecordService Realtime Subscriptions
DESCRIPTION: Provides examples of how to use the JavaScript SDK to subscribe to real-time changes for records in a PocketBase collection and how to unsubscribe from these updates. The `subscribe` method allows listening to changes for a specific record or all records in a topic, while `unsubscribe` can remove single or all subscriptions related to a topic.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_38

LANGUAGE: js
CODE:
```
// Subscribe to realtime changes to the specified topic ("*" or recordId).
//
// It is safe to subscribe multiple times to the same topic.
//
// You can use the returned UnsubscribeFunc to remove a single registered subscription.
// If you want to remove all subscriptions related to the topic use unsubscribe(topic).
pb.collection(collectionIdOrName).subscribe(topic, callback, options = {});

// Unsubscribe from all registered subscriptions to the specified topic ("*" or recordId).
// If topic is not set, then it will remove all registered collection subscriptions.
pb.collection(collectionIdOrName).unsubscribe([topic]);
```

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

TITLE: PocketBase RecordService CRUD Operations
DESCRIPTION: Illustrates the JavaScript SDK methods for performing standard Create, Read, Update, and Delete (CRUD) operations on records within a specified PocketBase collection. This includes examples for fetching single records, paginated lists, or all records in a batch, as well as creating, updating, and deleting entries.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_37

LANGUAGE: js
CODE:
```
// Returns a paginated records list.
pb.collection(collectionIdOrName).getList(page = 1, perPage = 30, options = {});

// Returns a list with all records batch fetched at once
// (by default 200 items per request; to change it set the `batch` param).
pb.collection(collectionIdOrName).getFullList(options = {});

// Returns the first found record matching the specified filter.
pb.collection(collectionIdOrName).getFirstListItem(filter, options = {});

// Returns a single record by its id.
pb.collection(collectionIdOrName).getOne(recordId, options = {});

// Creates (aka. register) a new record.
pb.collection(collectionIdOrName).create(bodyParams = {}, options = {});

// Updates an existing record by its id.
pb.collection(collectionIdOrName).update(recordId, bodyParams = {}, options = {});

// Deletes a single record by its id.
pb.collection(collectionIdOrName).delete(recordId, options = {});
```

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

TITLE: Initialize and Use PocketBase SDK
DESCRIPTION: Demonstrates basic initialization of the PocketBase SDK, authenticating a user with a password, and listing/filtering records from a collection.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_6

LANGUAGE: JavaScript
CODE:
```
import PocketBase from 'pocketbase';

const pb = new PocketBase('http://127.0.0.1:8090');

...

// authenticate as auth collection record
const userData = await pb.collection('users').authWithPassword('test@example.com', '123456');

// list and filter "example" collection records
const result = await pb.collection('example').getList(1, 20, {
    filter: 'status = true && created > "2022-08-01 10:00:00"'
});

// and much more...
```

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

TITLE: PocketBase Client Instance Methods Reference
DESCRIPTION: Detailed API documentation for the core methods available on the PocketBase client instance. These methods facilitate various functionalities such as sending HTTP requests, managing global request cancellation, and constructing full client URLs. Each method returns the `PocketBase` instance, allowing for method chaining.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_36

LANGUAGE: APIDOC
CODE:
```
pb.send(path, sendOptions = {})
  Description: Sends an api http request.
pb.autoCancellation(enable)
  Description: Globally enable or disable auto cancellation for pending duplicated requests.
pb.cancelAllRequests()
  Description: Cancels all pending requests.
pb.cancelRequest(cancelKey)
  Description: Cancels single request by its cancellation token key.
pb.buildURL(path)
  Description: Builds a full client url by safely concatenating the provided path.
```

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

TITLE: Initialize PocketBase JS SDK Client
DESCRIPTION: Demonstrates how to create a new instance of the PocketBase JavaScript SDK client, specifying the base URL for the PocketBase instance and the authentication store to be used. The default base URL is '/' and the default auth store is `LocalAuthStore`.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_35

LANGUAGE: js
CODE:
```
const pb = new PocketBase(baseURL = '/', authStore = LocalAuthStore);
```

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

TITLE: SvelteKit Server-Side Endpoint for User Authentication
DESCRIPTION: Shows how to create a server-side endpoint in SvelteKit to handle user login. It accesses the PocketBase instance from `event.locals` to perform authentication with email and password.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_25

LANGUAGE: js
CODE:
```
// src/routes/login/+server.js
/**
 * Creates a `POST /login` server-side endpoint
 *
 * @type {import('./$types').RequestHandler}
 */
export async function POST({ request, locals }) {
    const { email, password } = await request.json();

    const { token, record } = await locals.pb.collection('users').authWithPassword(email, password);

    return new Response('Success...');
}
```

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

TITLE: PocketBase JS SDK Development Commands
DESCRIPTION: Essential shell commands for developing with the PocketBase JS SDK, including running unit tests, formatting code with Prettier, and building/minifying the project for production deployment.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_49

LANGUAGE: sh
CODE:
```
# run unit tests
npm test

# run prettier
npm run format

# build and minify for production
npm run build
```

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

TITLE: Upload Files to PocketBase (FormData Object)
DESCRIPTION: Demonstrates the standard way to upload files using a `FormData` object, setting fields and file instances, which is then used to create a record in PocketBase.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_9

LANGUAGE: JavaScript
CODE:
```
// the standard way to create multipart/form-data body
const data = new FormData();
data.set('title', 'lorem ipsum...')
data.set('document', new File(...))

await pb.collection('example').create(data);
```

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

TITLE: SvelteKit SSR Integration with PocketBase Handle Hook
DESCRIPTION: Illustrates how to integrate PocketBase into a SvelteKit application using the `handle` hook. It initializes a PocketBase instance, loads auth data from cookies, refreshes authentication, and sets the auth cookie in the response.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_24

LANGUAGE: js
CODE:
```
// src/hooks.server.js
import PocketBase from 'pocketbase';

/** @type {import('@sveltejs/kit').Handle} */
export async function handle({ event, resolve }) {
    event.locals.pb = new PocketBase('http://127.0.0.1:8090');

    // load the store data from the request cookie string
    event.locals.pb.authStore.loadFromCookie(event.request.headers.get('cookie') || '');

    try {
        // get an up-to-date auth store state by verifying and refreshing the loaded auth model (if any)
        event.locals.pb.authStore.isValid && await event.locals.pb.collection('users').authRefresh();
    } catch (_) {
        // clear the auth store on failed refresh
        event.locals.pb.authStore.clear();
    }

    const response = await resolve(event);

    // send back the default 'pb_auth' cookie to the client with the latest store state
    response.headers.append('set-cookie', event.locals.pb.authStore.exportToCookie());

    return response;
}
```

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

TITLE: Configure Astro for Server-Side Rendering Output
DESCRIPTION: This snippet demonstrates how to set the `output` option to 'server' in Astro's configuration, enabling server-side rendering capabilities for your application.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_29

LANGUAGE: JavaScript
CODE:
```
import { defineConfig } from 'astro/config';

export default defineConfig({
    output: 'server'
});
```

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

TITLE: Listen for PocketBase Auth Store Changes
DESCRIPTION: Demonstrates how to register listeners using `pb.authStore.onChange` to react to authentication state changes. It shows how to set up callbacks that trigger on store updates, with an option for immediate execution upon registration, and how to remove listeners.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_15

LANGUAGE: js
CODE:
```
// triggered everytime on store change
const removeListener1 = pb.authStore.onChange((token, record) => {
    console.log('New store data 1:', token, record)
});

// triggered once right after registration and everytime on store change
const removeListener2 = pb.authStore.onChange((token, record) => {
    console.log('New store data 2:', token, record)
}, true);

// (optional) removes the attached listeners
removeListener1();
removeListener2();
```

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

TITLE: Initialize PocketBase Client in Nuxt 3 SSR Plugin
DESCRIPTION: This Nuxt 3 plugin initializes a PocketBase client, manages authentication state using `useCookie` for SSR, handles token refreshing, and provides the client instance to the Nuxt application context. It ensures the authentication store is kept in sync across server and client.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_30

LANGUAGE: JavaScript
CODE:
```
// plugins/pocketbase.js
import PocketBase from 'pocketbase';

export default defineNuxtPlugin(async () => {
  const pb = new PocketBase('http://127.0.0.1:8090');

  const cookie = useCookie('pb_auth', {
    path:     '/',
    secure:   true,
    sameSite: 'strict',
    httpOnly: false, // change to "true" if you want only server-side access
    maxAge:   604800,
  })

  // load the store data from the cookie value
  pb.authStore.save(cookie.value?.token, cookie.value?.record);

  // send back the default 'pb_auth' cookie to the client with the latest store state
  pb.authStore.onChange(() => {
    cookie.value = {
      token: pb.authStore.token,
      record: pb.authStore.record,
    };
  });

  try {
      // get an up-to-date auth store state by verifying and refreshing the loaded auth model (if any)
      pb.authStore.isValid && await pb.collection('users').authRefresh();
  } catch (_) {
      // clear the auth store on failed refresh
      pb.authStore.clear();
  }

  return {
    provide: { pb }
  }
});
```

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

TITLE: PocketBase JS SDK Settings Service API
DESCRIPTION: The SettingsService provides methods for managing and configuring various application settings within PocketBase. This includes retrieving all settings, performing bulk updates, testing S3 storage connections, sending test emails, and generating Apple OAuth2 client secrets.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_44

LANGUAGE: APIDOC
CODE:
```
// Returns a map with all available app settings.
pb.settings.getAll(options = {});

// Bulk updates app settings.
pb.settings.update(bodyParams = {}, options = {});

// Performs a S3 storage connection test.
pb.settings.testS3(filesystem = "storage", options = {});

// Sends a test email (verification, password-reset, email-change).
pb.settings.testEmail(collectionIdOrName, toEmail, template, options = {});

// Generates a new Apple OAuth2 client secret.
pb.settings.generateAppleClientSecret(clientId, teamId, keyId, privateKey, duration, options = {});
```

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

TITLE: Astro SSR Integration with PocketBase Middleware
DESCRIPTION: Demonstrates how to integrate PocketBase into an Astro application using middleware. It initializes a PocketBase instance, loads auth data from cookies, refreshes authentication, and sets the auth cookie in the response.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_27

LANGUAGE: ts
CODE:
```
// src/middleware/index.ts
import PocketBase from 'pocketbase';

import { defineMiddleware } from 'astro/middleware';

export const onRequest = defineMiddleware(async ({ locals, request }: any, next: () => any) => {
    locals.pb = new PocketBase('http://127.0.0.1:8090');

    // load the store data from the request cookie string
    locals.pb.authStore.loadFromCookie(request.headers.get('cookie') || '');

    try {
        // get an up-to-date auth store state by verifying and refreshing the loaded auth record (if any)
        locals.pb.authStore.isValid && await locals.pb.collection('users').authRefresh();
    } catch (_) {
        // clear the auth store on failed refresh
        locals.pb.authStore.clear();
    }

    const response = await next();

    // send back the default 'pb_auth' cookie to the client with the latest store state
    response.headers.append('set-cookie', locals.pb.authStore.exportToCookie());

    return response;
});
```

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

TITLE: Import PocketBase JS SDK in Node.js
DESCRIPTION: Illustrates how to import the PocketBase JavaScript SDK in Node.js, showing both ES module (default) and CommonJS module syntax.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_3

LANGUAGE: JavaScript
CODE:
```
// Using ES modules (default)
import PocketBase from 'pocketbase'

// OR if you are using CommonJS modules
const PocketBase = require('pocketbase/cjs')
```

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

TITLE: PocketBase JS SDK Batch Operations
DESCRIPTION: Demonstrates how to create and send a batch request to perform multiple create, update, delete, or upsert operations efficiently. This allows for combining several API calls into a single network request, improving performance.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_40

LANGUAGE: JavaScript
CODE:
```
// create a new batch instance
const batch = pb.createBatch();

// register create/update/delete/upsert requests to the created batch
batch.collection('example1').create({ ... });
batch.collection('example2').update('RECORD_ID', { ... });
batch.collection('example3').delete('RECORD_ID');
batch.collection('example4').upsert({ ... });

// send the batch request
const result = await batch.send()
```

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

TITLE: Initialize PocketBase Client in Nuxt 2 SSR Plugin
DESCRIPTION: This Nuxt 2 plugin initializes a PocketBase client, loads authentication state from incoming request cookies, sets response headers to update cookies, and refreshes authentication tokens. It injects the PocketBase instance into the Nuxt context for use throughout the application.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_32

LANGUAGE: JavaScript
CODE:
```
// plugins/pocketbase.js
import PocketBase from  'pocketbase';

export default async (ctx, inject) => {
  const pb = new PocketBase('http://127.0.0.1:8090');

  // load the store data from the request cookie string
  pb.authStore.loadFromCookie(ctx.req?.headers?.cookie || '');

  // send back the default 'pb_auth' cookie to the client with the latest store state
  pb.authStore.onChange(() => {
    ctx.res?.setHeader('set-cookie', pb.authStore.exportToCookie());
  });

  try {
      // get an up-to-date auth store state by verifying and refreshing the loaded auth record (if any)
      pb.authStore.isValid && await pb.collection('users').authRefresh();
  } catch (_) {
      // clear the auth store on failed refresh
      pb.authStore.clear();
  }

  inject('pocketbase', pb);
};
```

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

TITLE: PocketBase JS SDK Backup Service API
DESCRIPTION: The BackupService provides functionalities for managing application data backups. This includes listing available backup files, initiating new backups, uploading existing backup files, deleting specific backups, restoring data from a backup, and generating secure download URLs for backup files.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_46

LANGUAGE: APIDOC
CODE:
```
// Returns list with all available backup files.
pb.backups.getFullList(options = {});

// Initializes a new backup.
pb.backups.create(basename = "", options = {});

// Upload an existing app data backup.
pb.backups.upload({ file: File/Blob }, options = {});

// Deletes a single backup by its name.
pb.backups.delete(key, options = {});

// Initializes an app data restore from an existing backup.
pb.backups.restore(key, options = {});

// Builds a download url for a single existing backup using a
// superuser file token and the backup file key.
pb.backups.getDownloadURL(token, key);
```

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

TITLE: Implement Custom Auth Store for PocketBase JS SDK
DESCRIPTION: Illustrates how to create a custom authentication store by extending `BaseAuthStore`. This allows developers to integrate custom business logic, such as logging or additional data synchronization, during authentication state changes.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_13

LANGUAGE: js
CODE:
```
import PocketBase, { BaseAuthStore } from 'pocketbase';

class CustomAuthStore extends BaseAuthStore {
    save(token, model) {
        super.save(token, model);

        // your custom business logic...
    }
}

const pb = new PocketBase('http://127.0.0.1:8090', new CustomAuthStore());
```

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

TITLE: Astro Component Script for User Authentication
DESCRIPTION: Shows how to access the PocketBase instance from `Astro.locals` within an Astro component's script to perform user authentication.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_28

LANGUAGE: ts
CODE:
```
// src/pages/index.astro
---
const locals = Astro.locals;

const userAuth = async () => {
    const { token, record } = await locals.pb.collection('users').authWithPassword('test@example.com', '123456');

    return new Response('Success...');
};
---
```

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

TITLE: PocketBase AuthStore Cookie Helper Methods
DESCRIPTION: Demonstrates how to load authentication data from a cookie string into the PocketBase auth store and export the store's data back into a cookie string, with options for cookie attributes.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_23

LANGUAGE: js
CODE:
```
// update the store with the parsed data from the cookie string
pb.authStore.loadFromCookie('pb_auth=...');

// exports the store data as cookie, with option to extend the default SameSite, Secure, HttpOnly, Path and Expires attributes
pb.authStore.exportToCookie({ httpOnly: false }); // Output: 'pb_auth=...'
```

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

TITLE: Configure Custom Request Options for PocketBase JS SDK Calls
DESCRIPTION: Pass an `options` argument to PocketBase API service calls to customize request behavior. This includes setting custom headers, fetch options, or providing a custom fetch implementation for fine-grained control.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_20

LANGUAGE: js
CODE:
```
pb.collection('example').getList(1, 20, {
    expand:          'someRel',
    otherQueryParam: '123',

    // custom headers
    headers: {
        'X-Custom-Header': 'example'
    },

    // custom fetch options
    keepalive: false,
    cache:     'no-store',

    // or custom fetch implementation
    fetch: async (url, config) => { ... }
})
```

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

TITLE: Handle PocketBase JS SDK Promise Errors
DESCRIPTION: Demonstrates how to handle errors from PocketBase JS SDK calls using both Promise `.then().catch()` syntax and `async/await` with `try/catch` blocks for robust error management.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_10

LANGUAGE: js
CODE:
```
pb.collection('example').getList(1, 50).then((result) => {
  // success...
  console.log('Result:', result);
}).catch((error) => {
  // error...
  console.log('Error:', error);
});

// OR if you are using the async/await syntax:
try {
  const result = await pb.collection('example').getList(1, 50);
  console.log('Result:', result);
} catch (error) {
  console.log('Error:', error);
}
```

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

TITLE: PocketBase JS SDK Realtime Service API
DESCRIPTION: The RealtimeService manages the WebSocket connection and subscriptions for real-time events in PocketBase. It allows clients to subscribe to specific topics, unsubscribe, check connection status, and define custom handlers for disconnect events. Note that record-specific subscriptions are handled by the `pb.collection()` RecordService.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_45

LANGUAGE: APIDOC
CODE:
```
// Initialize the realtime connection (if not already) and register the subscription listener.
//
// You can subscribe to the `PB_CONNECT` event if you want to listen to the realtime connection connect/reconnect events.
pb.realtime.subscribe(topic, callback, options = {});

// Unsubscribe from all subscription listeners with the specified topic.
pb.realtime.unsubscribe(topic?);

// Unsubscribe from all subscription listeners starting with the specified topic prefix.
pb.realtime.unsubscribeByPrefix(topicPrefix);

// Unsubscribe from all subscriptions matching the specified topic and listener function.
pb.realtime.unsubscribeByTopicAndListener(topic, callback);

// Getter that checks whether the realtime connection has been established.
pb.realtime.isConnected

// An optional hook that is invoked when the realtime client disconnects
// either when unsubscribing from all subscriptions or when the connection
// was interrupted or closed by the server.
//
// Note that the realtime client autoreconnect on its own and this hook is
// useful only for the cases where you want to apply a special behavior on
// server error or after closing the realtime connection.
pb.realtime.onDisconnect = function(activeSubscriptions)
```

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

TITLE: Upload Files to PocketBase (Plain Object)
DESCRIPTION: Shows how to upload files to PocketBase by providing a plain JavaScript object where file properties are `File` or `Blob` instances. The SDK automatically converts this to `FormData`.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_8

LANGUAGE: JavaScript
CODE:
```
const data = {
      'title':    'lorem ipsum...', 
      'document': new File(...),
    };

    await pb.collection('example').create(data);
```

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

TITLE: Create a Global Typed PocketBase Instance for Enhanced Type Safety
DESCRIPTION: Create a global `TypedPocketBase` interface to provide strong typing for specific collections. This approach eliminates the need to specify generics on every individual SDK call, improving code readability.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_19

LANGUAGE: ts
CODE:
```
interface Task {
  id:   string;
  name: string;
}

interface Post {
  id:     string;
  title:  string;
  active: boolean;
}

interface TypedPocketBase extends PocketBase {
  collection(idOrName: string): RecordService // default fallback for any other collection
  collection(idOrName: 'tasks'): RecordService<Task>
  collection(idOrName: 'posts'): RecordService<Post>
}

...

const pb = new PocketBase("http://127.0.0.1:8090") as TypedPocketBase;

pb.collection('tasks').getOne("RECORD_ID") // -> results in Promise<Task>
pb.collection('posts').getOne("RECORD_ID") // -> results in Promise<Post>
```

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

TITLE: PocketBase JS SDK Authentication Handlers
DESCRIPTION: Methods available for 'auth' type collections to manage user authentication, including login, password reset, email verification, and external OAuth2 integrations. These methods interact with the PocketBase backend to handle user sessions and credentials.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_39

LANGUAGE: APIDOC
CODE:
```
pb.collection(collectionIdOrName).listAuthMethods(options = {});
pb.collection(collectionIdOrName).authWithPassword(usernameOrEmail, password, options = {});
pb.collection(collectionIdOrName).authWithOTP(otpId, password, options = {});
pb.collection(collectionIdOrName).authWithOAuth2(authConfig);
pb.collection(collectionIdOrName).authWithOAuth2Code(provider, code, codeVerifier, redirectUrl, createData = {}, options = {});
pb.collection(collectionIdOrName).authRefresh(options = {});
pb.collection(collectionIdOrName).requestOTP(email, options = {});
pb.collection(collectionIdOrName).requestPasswordReset(email, options = {});
pb.collection(collectionIdOrName).confirmPasswordReset(resetToken, newPassword, newPasswordConfirm, options = {});
pb.collection(collectionIdOrName).requestVerification(email, options = {});
pb.collection(collectionIdOrName).confirmVerification(verificationToken, options = {});
pb.collection(collectionIdOrName).requestEmailChange(newEmail, options = {});
pb.collection(collectionIdOrName).confirmEmailChange(emailChangeToken, userPassword, options = {});
pb.collection(collectionIdOrName).listExternalAuths(recordId, options = {});
pb.collection(collectionIdOrName).unlinkExternalAuth(recordId, provider, options = {});
pb.collection(collectionIdOrName).impersonate(recordId, duration, options = {});
```

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

TITLE: PocketBase JS SDK File Management
DESCRIPTION: Methods for managing files associated with records, including generating absolute URLs for record files and requesting private file access tokens. These functions are crucial for handling file uploads and downloads securely.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_41

LANGUAGE: APIDOC
CODE:
```
pb.files.getURL(record, filename, options = {});
pb.files.getToken(options = {});
```

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

TITLE: Bind Filter Parameters with pb.filter Method
DESCRIPTION: Explains how to use `pb.filter(expr, params)` to safely generate filter strings with placeholder parameters, preventing string injection attacks, especially in server-side Node.js queries.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_7

LANGUAGE: JavaScript
CODE:
```
const records = await pb.collection("example").getList(1, 20, {
  // the same as: "title ~ 'te\'st' && (totalA = 123 || totalB = 123)"
  filter: pb.filter("title ~ {:title} && (totalA = {:num} || totalB = {:num})", { title: "te'st", num: 123 })
})
```

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

TITLE: PocketBase JS SDK Log Management
DESCRIPTION: Methods for retrieving application logs, including paginated lists, single log entries by ID, and log statistics. These functions are useful for monitoring application activity and debugging.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_43

LANGUAGE: APIDOC
CODE:
```
pb.logs.getList(page = 1, perPage = 30, options = {});
pb.logs.getOne(id, options = {});
pb.logs.getStats(options = {});
```

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

TITLE: PocketBase JS SDK Collection Management
DESCRIPTION: Methods for managing collections within PocketBase, including listing, retrieving, creating, updating, deleting, truncating, importing, and scaffolding collection models. These functions provide comprehensive control over the database schema and data.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_42

LANGUAGE: APIDOC
CODE:
```
pb.collections.getList(page = 1, perPage = 30, options = {});
pb.collections.getFullList(options = {});
pb.collections.getFirstListItem(filter, options = {});
pb.collections.getOne(idOrName, options = {});
pb.collections.create(bodyParams = {}, options = {});
pb.collections.update(idOrName, bodyParams = {}, options = {});
pb.collections.delete(idOrName, options = {});
pb.collections.truncate(idOrName, options = {});
pb.collections.import(collections, deleteMissing = false, options = {});
pb.collections.getScaffolds(options = {});
```

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

TITLE: SvelteKit Global Type Definition for PocketBase Locals
DESCRIPTION: Provides a TypeScript declaration to ensure proper type detection for the PocketBase instance stored in `event.locals` within a SvelteKit application.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_26

LANGUAGE: ts
CODE:
```
// src/app.d.ts
import PocketBase from 'pocketbase';

declare global {
    declare namespace App {
        interface Locals {
            pb: PocketBase
        }
    }
}
```

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

TITLE: Define Custom TypeScript Interfaces for PocketBase Records
DESCRIPTION: Define a TypeScript interface for a PocketBase record model. Use generics with SDK methods like `getList` and `getOne` to ensure type safety for retrieved collection data.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_18

LANGUAGE: ts
CODE:
```
interface Task {
  // type the collection fields you want to use...
  id:   string;
  name: string;
}

pb.collection('tasks').getList<Task>(1, 20) // -> results in Promise<ListResult<Task>>
pb.collection('tasks').getOne<Task>("RECORD_ID")  // -> results in Promise<Task>
```

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

TITLE: PocketBase ClientResponseError Object Structure
DESCRIPTION: Defines the structure of the `ClientResponseError` object returned by the PocketBase JS SDK on API call failures. It includes details like the requested URL, HTTP status code, the API's JSON error response, and flags for abort or original non-normalized errors.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_11

LANGUAGE: APIDOC
CODE:
```
ClientResponseError {
    url:           string,     // requested url
    status:        number,     // response status code
    response:      { ... },    // the API JSON error response
    isAbort:       boolean,    // is abort/cancellation error
    originalError: Error|null, // the original non-normalized error
}
```

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

TITLE: PocketBase BaseAuthStore Public Members API
DESCRIPTION: Documents the public fields and methods available in the `BaseAuthStore` class, which serves as the base for default and custom authentication stores in the PocketBase JS SDK. It details properties like `record`, `token`, `isValid`, and methods for clearing, saving, and listening to store changes.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_14

LANGUAGE: APIDOC
CODE:
```
BaseAuthStore {
    // base fields
    record:       RecordModel|null // the authenticated auth record
    token:        string  // the authenticated token
    isValid:      boolean // checks if the store has existing and unexpired token
    isSuperuser:  boolean // checks if the store state is for superuser

    // main methods
    clear()             // "logout" the authenticated record
    save(token, record) // update the store with the new auth data
    onChange(callback, fireImmediately = false) // register a callback that will be called on store change

    // cookie parse and serialize helpers
    loadFromCookie(cookieHeader, key = 'pb_auth')
    exportToCookie(options = {}, key = 'pb_auth')
}
```

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

TITLE: PocketBase JS SDK: Intercept and Modify Request with `beforeSend` Hook
DESCRIPTION: The `beforeSend` hook in the PocketBase JS SDK allows developers to inspect and modify the `fetch` request configuration just before it is sent. This is useful for adding custom headers or altering other request options globally. It expects an object with `url` and `options` to be returned.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_21

LANGUAGE: javascript
CODE:
```
const pb = new PocketBase('http://127.0.0.1:8090');

pb.beforeSend = function (url, options) {
    // For list of the possible request options properties check
    // https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
    options.headers = Object.assign({}, options.headers, {
        'X-Custom-Header': 'example',
    });

    return { url, options };
};

// use the created client as usual...
```

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

TITLE: PocketBase JS SDK Health Service API
DESCRIPTION: The HealthService provides a simple method to check the operational status of the PocketBase API, useful for monitoring and readiness checks.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_48

LANGUAGE: APIDOC
CODE:
```
// Checks the health status of the api.
pb.health.check(options = {});
```

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

TITLE: PocketBase JS SDK Cron Service API
DESCRIPTION: The CronService allows interaction with scheduled cron jobs within the PocketBase application. It provides methods to retrieve a list of all available cron jobs and to manually trigger the execution of a specific job by its ID.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_47

LANGUAGE: APIDOC
CODE:
```
// Returns list with all available cron jobs.
pb.crons.getFullList(options = {});

// Runs the specified cron job.
pb.crons.run(jobId, options = {});
```

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

TITLE: Control PocketBase JS SDK Request Cancellation
DESCRIPTION: Control auto-cancellation using `requestKey` for per-request behavior, allowing or preventing cancellation. This snippet also demonstrates how to globally disable auto-cancellation for all SDK requests.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_17

LANGUAGE: js
CODE:
```
pb.collection('example').getList(1, 20);                        // cancelled
pb.collection('example').getList(1, 20);                        // executed
pb.collection('example').getList(1, 20, { requestKey: "test" }) // cancelled
pb.collection('example').getList(1, 20, { requestKey: "test" }) // executed
pb.collection('example').getList(1, 20, { requestKey: null })   // executed
pb.collection('example').getList(1, 20, { requestKey: null })   // executed

// globally disable auto cancellation
pb.autoCancellation(false);

pb.collection('example').getList(1, 20); // executed
pb.collection('example').getList(1, 20); // executed
pb.collection('example').getList(1, 20); // executed
```

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

TITLE: PocketBase JS SDK: Process and Modify Response with `afterSend` Hook
DESCRIPTION: The `afterSend` hook in the PocketBase JS SDK is triggered after a `fetch` request successfully completes. It provides access to the raw response object and its parsed data, enabling inspection, logging, or modification of the response data before it's returned to the caller. It expects the modified data to be returned.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_22

LANGUAGE: javascript
CODE:
```
const pb = new PocketBase('http://127.0.0.1:8090');

pb.afterSend = function (response, data) {
    // do something with the response state
    console.log(response.status);

    return Object.assign(data, {
        // extend the data...
        "additionalField": 123,
    });
};

// use the created client as usual...
```

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

TITLE: Handle Duplicated PocketBase JS SDK Requests
DESCRIPTION: The PocketBase JS SDK automatically cancels duplicated pending requests, executing only the last one. This behavior prevents redundant API calls for identical requests.

SOURCE: https://github.com/pocketbase/js-sdk/blob/master/README.md#_snippet_16

LANGUAGE: js
CODE:
```
pb.collection('example').getList(1, 20) // cancelled
pb.collection('example').getList(2, 20) // cancelled
pb.collection('example').getList(3, 20) // executed
```