@vendure/docs 0.0.0-202601161541

package/docs/reference/core-plugins/sentry-plugin/index.md

@@ -0,0 +1,158 @@
+---
+title: "SentryPlugin"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## SentryPlugin
+
+<GenerationInfo sourceFile="packages/sentry-plugin/src/sentry-plugin.ts" sourceLine="146" packageName="@vendure/sentry-plugin" />
+
+This plugin integrates the [Sentry](https://sentry.io) error tracking & performance monitoring
+service with your Vendure server. In addition to capturing errors, it also provides built-in
+support for [tracing](https://docs.sentry.io/product/sentry-basics/concepts/tracing/) as well as
+enriching your Sentry events with additional context about the request.
+
+:::info
+This documentation applies from v3.5.0 of the plugin, which works differently to previous
+versions. Documentation for prior versions can
+be found [here](https://github.com/vendurehq/vendure/blob/1bb9cf8ca1584bce026ccc82f33f866b766ef47d/packages/sentry-plugin/src/sentry-plugin.ts).
+:::
+
+## Pre-requisites
+
+This plugin depends on access to Sentry, which can be self-hosted or used as a cloud service.
+
+If using the hosted SaaS option, you must have a Sentry account and a project set up ([sign up here](https://sentry.io/signup/)). When setting up your project,
+select the "Node.js" platform and no framework.
+
+Once set up, you will be given a [Data Source Name (DSN)](https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/)
+which you will need to provide to the plugin.
+
+## Installation
+
+```sh
+npm install --save @vendure/sentry-plugin
+```
+
+## Environment Variables
+
+The following environment variables are used to control how the Sentry
+integration behaves:
+
+- `SENTRY_DSN`: (required) Sentry Data Source Name
+- `SENTRY_TRACES_SAMPLE_RATE`: Number between 0 and 1
+- `SENTRY_PROFILES_SAMPLE_RATE`: Number between 0 and 1
+- `SENTRY_ENABLE_LOGS`: Boolean. Captures calls to the console API as logs in Sentry. Default `false`
+- `SENTRY_CAPTURE_LOG_LEVELS`: 'debug' | 'info' | 'warn' | 'error' | 'log' | 'assert' | 'trace'
+
+## Configuration
+
+Setting up the Sentry plugin requires two steps:
+
+### Step 1: Preload the Sentry instrument file
+
+Make sure the `SENTRY_DSN` environment variable is defined.
+
+The Sentry SDK must be initialized before your application starts. This is done by preloading
+the instrument file when starting your Vendure server:
+
+```sh
+node --import @vendure/sentry-plugin/instrument ./dist/index.js
+```
+
+Or if using TypeScript directly with tsx:
+
+```sh
+tsx --import @vendure/sentry-plugin/instrument ./src/index.ts
+```
+
+### Step 2: Add the SentryPlugin to your Vendure config
+
+```ts
+import { VendureConfig } from '@vendure/core';
+import { SentryPlugin } from '@vendure/sentry-plugin';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        // ...
+        // highlight-start
+        SentryPlugin.init({
+            // Optional configuration
+            includeErrorTestMutation: true,
+        }),
+        // highlight-end
+    ],
+};
+```
+
+## Tracing
+
+This plugin includes built-in support for [tracing](https://docs.sentry.io/product/sentry-basics/concepts/tracing/), which allows you to see the performance of your.
+To enable tracing, preload the instrument file as described in [Step 1](#step-1-preload-the-sentry-instrument-file).
+This ensures that the Sentry SDK is initialized before any other code is executed.
+
+You can also set the `tracesSampleRate` and `profilesSampleRate` options to control the sample rate for
+tracing and profiling, with the following environment variables:
+
+- `SENTRY_TRACES_SAMPLE_RATE`
+- `SENTRY_PROFILES_SAMPLE_RATE`
+
+The sample rate for tracing should be between 0 and 1. The sample rate for profiling should be between 0 and 1.
+
+By default, both are set to `undefined`, which means that tracing and profiling are disabled.
+
+## Instrumenting your own code
+
+You may want to add your own custom spans to your code. To do so, you can use the `Sentry` object
+from the `@sentry/node` package. For example:
+
+```ts
+import * as Sentry from "@sentry/node";
+
+export class MyService {
+    async myMethod() {
+         Sentry.setContext('My Custom Context,{
+             key: 'value',
+         });
+    }
+}
+```
+
+## Error test mutation
+
+To test whether your Sentry configuration is working correctly, you can set the `includeErrorTestMutation` option to `true`. This will add a mutation to the Admin API
+which will throw an error of the type specified in the `errorType` argument. For example:
+
+```graphql
+mutation CreateTestError {
+    createTestError(errorType: DATABASE_ERROR)
+}
+```
+
+You should then be able to see the error in your Sentry dashboard (it may take a couple of minutes to appear).
+
+```ts title="Signature"
+class SentryPlugin {
+    static options: SentryPluginOptions = {} as any;
+    init(options?: SentryPluginOptions) => ;
+}
+```
+
+<div className="members-wrapper">
+
+### options
+
+<MemberInfo kind="property" type={`<a href='/reference/core-plugins/sentry-plugin/sentry-plugin-options#sentrypluginoptions'>SentryPluginOptions</a>`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(options?: <a href='/reference/core-plugins/sentry-plugin/sentry-plugin-options#sentrypluginoptions'>SentryPluginOptions</a>) => `}   />
+
+
+
+
+</div>

package/docs/reference/core-plugins/sentry-plugin/sentry-plugin-options.md

@@ -0,0 +1,32 @@
+---
+title: "SentryPluginOptions"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## SentryPluginOptions
+
+<GenerationInfo sourceFile="packages/sentry-plugin/src/types.ts" sourceLine="7" packageName="@vendure/sentry-plugin" />
+
+Configuration options for the <a href='/reference/core-plugins/sentry-plugin/#sentryplugin'>SentryPlugin</a>.
+
+```ts title="Signature"
+interface SentryPluginOptions {
+    includeErrorTestMutation?: boolean;
+}
+```
+
+<div className="members-wrapper">
+
+### includeErrorTestMutation
+
+<MemberInfo kind="property" type={`boolean`} default={`false`}   />
+
+Whether to include the error test mutation in the admin API.
+When enabled, a `createTestError` mutation becomes available in
+the Admin API, which can be used to create different types of error
+to check that the integration is working correctly.
+
+
+</div>

package/docs/reference/core-plugins/sentry-plugin/sentry-service.md

@@ -0,0 +1,47 @@
+---
+title: "SentryService"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## SentryService
+
+<GenerationInfo sourceFile="packages/sentry-plugin/src/sentry.service.ts" sourceLine="13" packageName="@vendure/sentry-plugin" />
+
+Service for capturing errors and messages to Sentry.
+
+```ts title="Signature"
+class SentryService {
+    constructor(options: SentryPluginOptions)
+    captureException(exception: Error) => ;
+    captureMessage(message: string, captureContext?: CaptureContext) => ;
+    startSpan(context: StartSpanOptions) => ;
+}
+```
+
+<div className="members-wrapper">
+
+### constructor
+
+<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/sentry-plugin/sentry-plugin-options#sentrypluginoptions'>SentryPluginOptions</a>) => SentryService`}   />
+
+
+### captureException
+
+<MemberInfo kind="method" type={`(exception: Error) => `}   />
+
+
+### captureMessage
+
+<MemberInfo kind="method" type={`(message: string, captureContext?: CaptureContext) => `}   />
+
+Captures a message
+### startSpan
+
+<MemberInfo kind="method" type={`(context: StartSpanOptions) => `}   />
+
+Starts new span
+
+
+</div>

package/docs/reference/core-plugins/stellate-plugin/index.md

@@ -0,0 +1,277 @@
+---
+title: "StellatePlugin"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## StellatePlugin
+
+<GenerationInfo sourceFile="packages/stellate-plugin/src/stellate-plugin.ts" sourceLine="246" packageName="@vendure/stellate-plugin" since="2.1.5" />
+
+A plugin to integrate the [Stellate](https://stellate.co/) GraphQL caching service with your Vendure server.
+The main purpose of this plugin is to ensure that cached data gets correctly purged in
+response to events inside Vendure. For example, changes to a Product's description should
+purge any associated record for that Product in Stellate's cache.
+
+## Pre-requisites
+
+You will first need to [set up a free Stellate account](https://stellate.co/signup).
+
+You will also need to generate an **API token** for the Stellate Purging API. For instructions on how to generate the token,
+see the [Stellate Purging API docs](https://docs.stellate.co/docs/purging-api#authentication).
+
+## Installation
+
+```
+npm install @vendure/stellate-plugin
+```
+
+## Configuration
+
+The plugin is configured via the `StellatePlugin.init()` method. This method accepts an options object
+which defines the Stellate service name and API token, as well as an array of <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a>s which
+define how the plugin will respond to Vendure events in order to trigger calls to the
+Stellate [Purging API](https://stellate.co/docs/graphql-edge-cache/purging-api).
+
+*Example*
+
+```ts
+import { StellatePlugin, defaultPurgeRules } from '@vendure/stellate-plugin';
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+   // ...
+   plugins: [
+       StellatePlugin.init({
+           // The Stellate service name, i.e. `<serviceName>.stellate.sh`
+           serviceName: 'my-service',
+           // The API token for the Stellate Purging API. See the "pre-requisites" section above.
+           apiToken: process.env.STELLATE_PURGE_API_TOKEN,
+           devMode: !isProd || process.env.STELLATE_DEBUG_MODE ? true : false,
+           debugLogging: process.env.STELLATE_DEBUG_MODE ? true : false,
+           purgeRules: [
+               ...defaultPurgeRules,
+               // custom purge rules can be added here
+           ],
+       }),
+   ],
+};
+```
+
+In your Stellate dashboard, you can use the following configuration example as a sensible default for a
+Vendure application:
+
+*Example*
+
+```ts
+import { Config } from "stellate";
+
+const config: Config = {
+  config: {
+    name: "my-vendure-server",
+    originUrl: "https://my-vendure-server.com/shop-api",
+    ignoreOriginCacheControl: true,
+    passThroughOnly: false,
+    scopes: {
+      SESSION_BOUND: "header:authorization|cookie:session",
+    },
+    headers: {
+      "access-control-expose-headers": "vendure-auth-token",
+    },
+    rootTypeNames: {
+      query: "Query",
+      mutation: "Mutation",
+    },
+    keyFields: {
+      types: {
+        SearchResult: ["productId"],
+        SearchResponseCacheIdentifier: ["collectionSlug"],
+      },
+    },
+    rules: [
+      {
+        types: [
+          "Product",
+          "Collection",
+          "ProductVariant",
+          "SearchResponse",
+        ],
+        maxAge: 900,
+        swr: 900,
+        description: "Cache Products & Collections",
+      },
+      {
+        types: ["Channel"],
+        maxAge: 9000,
+        swr: 9000,
+        description: "Cache active channel",
+      },
+      {
+        types: ["Order", "Customer", "User"],
+        maxAge: 0,
+        swr: 0,
+        description: "Do not cache user data",
+      },
+    ],
+  },
+};
+export default config;
+```
+
+## Storefront setup
+
+In your storefront, you should point your GraphQL client to the Stellate GraphQL API endpoint, which is
+`https://<service-name>.stellate.sh`.
+
+Wherever you are using the `search` query (typically in product listing & search pages), you should also add the
+`cacheIdentifier` field to the query. This will ensure that the Stellate cache is correctly purged when
+a Product or Collection is updated.
+
+*Example*
+
+```ts
+import { graphql } from '../generated/gql';
+
+export const searchProductsDocument = graphql(`
+    query SearchProducts($input: SearchInput!) {
+        search(input: $input) {
+            // highlight-start
+            cacheIdentifier {
+                collectionSlug
+            }
+            // highlight-end
+            items {
+               # ...
+            }
+        }
+    }
+}`);
+```
+
+## Custom PurgeRules
+
+The configuration above only accounts for caching of some of the built-in Vendure entity types. If you have
+custom entity types, you may well want to add them to the Stellate cache. In this case, you'll also need a way to
+purge those entities from the cache when they are updated. This is where the <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a> comes in.
+
+Let's imagine that you have built a simple CMS plugin for Vendure which exposes an `Article` entity in your Shop API, and
+you have added this to your Stellate configuration:
+
+*Example*
+
+```ts
+import { Config } from "stellate";
+
+const config: Config = {
+    config: {
+        // ...
+        rules: [
+            // ...
+            {
+                types: ["Article"],
+                maxAge: 900,
+                swr: 900,
+                description: "Cache Articles",
+            },
+        ],
+    },
+    // ...
+};
+export default config;
+```
+
+You can then add a custom <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a> to the StellatePlugin configuration:
+
+*Example*
+
+```ts
+import { StellatePlugin, defaultPurgeRules } from "@vendure/stellate-plugin";
+import { VendureConfig } from "@vendure/core";
+import { ArticleEvent } from "./plugins/cms/events/article-event";
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        StellatePlugin.init({
+            // ...
+            purgeRules: [
+                ...defaultPurgeRules,
+                new PurgeRule({
+                    eventType: ArticleEvent,
+                    handler: async ({ events, stellateService }) => {
+                        const articleIds = events.map((e) => e.article.id);
+                        stellateService.purge("Article", articleIds);
+                    },
+                }),
+            ],
+        }),
+    ],
+};
+```
+
+## DevMode & Debug Logging
+
+In development, you can set `devMode: true`, which will prevent any calls being made to the Stellate Purging API.
+
+If you want to log the calls that _would_ be made to the Stellate Purge API when in devMode, you can set `debugLogging: true`.
+Note that debugLogging generates a lot of debug-level logging, so it is recommended to only enable this when needed.
+
+*Example*
+
+```ts
+import { StellatePlugin, defaultPurgeRules } from '@vendure/stellate-plugin';
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+   // ...
+   plugins: [
+       StellatePlugin.init({
+           // ...
+           devMode: !process.env.PRODUCTION,
+           debugLogging: process.env.STELLATE_DEBUG_MODE ? true : false,
+           purgeRules: [
+               ...defaultPurgeRules,
+           ],
+       }),
+   ],
+};
+```
+
+```ts title="Signature"
+class StellatePlugin implements OnApplicationBootstrap {
+    static options: StellatePluginOptions;
+    init(options: StellatePluginOptions) => ;
+    constructor(options: StellatePluginOptions, eventBus: EventBus, stellateService: StellateService, moduleRef: ModuleRef)
+    onApplicationBootstrap() => ;
+}
+```
+* Implements: <code>OnApplicationBootstrap</code>
+
+
+
+<div className="members-wrapper">
+
+### options
+
+<MemberInfo kind="property" type={`<a href='/reference/core-plugins/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>) => `}   />
+
+
+### constructor
+
+<MemberInfo kind="method" type={`(options: <a href='/reference/core-plugins/stellate-plugin/stellate-plugin-options#stellatepluginoptions'>StellatePluginOptions</a>, eventBus: <a href='/reference/typescript-api/events/event-bus#eventbus'>EventBus</a>, stellateService: <a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a>, moduleRef: ModuleRef) => StellatePlugin`}   />
+
+
+### onApplicationBootstrap
+
+<MemberInfo kind="method" type={`() => `}   />
+
+
+
+
+</div>

package/docs/reference/core-plugins/stellate-plugin/purge-rule.md

@@ -0,0 +1,91 @@
+---
+title: "PurgeRule"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## PurgeRule
+
+<GenerationInfo sourceFile="packages/stellate-plugin/src/purge-rule.ts" sourceLine="49" packageName="@vendure/stellate-plugin" />
+
+Defines a rule that listens for a particular VendureEvent and uses that to
+make calls to the [Stellate Purging API](https://docs.stellate.co/docs/purging-api) via
+the provided <a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a> instance.
+
+```ts title="Signature"
+class PurgeRule<Event extends VendureEvent = VendureEvent> {
+    eventType: Type<Event>
+    bufferTimeMs: number | undefined
+    handle(handlerArgs: { events: Event[]; stellateService: StellateService; injector: Injector }) => ;
+    constructor(config: PurgeRuleConfig<Event>)
+}
+```
+
+<div className="members-wrapper">
+
+### eventType
+
+<MemberInfo kind="property" type={`Type&#60;Event&#62;`}   />
+
+
+### bufferTimeMs
+
+<MemberInfo kind="property" type={`number | undefined`}   />
+
+
+### handle
+
+<MemberInfo kind="method" type={`(handlerArgs: { events: Event[]; stellateService: <a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a>; injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a> }) => `}   />
+
+
+### constructor
+
+<MemberInfo kind="method" type={`(config: <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgeruleconfig'>PurgeRuleConfig</a>&#60;Event&#62;) => PurgeRule`}   />
+
+
+
+
+</div>
+
+
+## PurgeRuleConfig
+
+<GenerationInfo sourceFile="packages/stellate-plugin/src/purge-rule.ts" sourceLine="13" packageName="@vendure/stellate-plugin" />
+
+Configures a <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a>.
+
+```ts title="Signature"
+interface PurgeRuleConfig<Event extends VendureEvent> {
+    eventType: Type<Event>;
+    bufferTime?: number;
+    handler: (handlerArgs: {
+        events: Event[];
+        stellateService: StellateService;
+        injector: Injector;
+    }) => void | Promise<void>;
+}
+```
+
+<div className="members-wrapper">
+
+### eventType
+
+<MemberInfo kind="property" type={`Type&#60;Event&#62;`}   />
+
+Specifies which VendureEvent will trigger this purge rule.
+### bufferTime
+
+<MemberInfo kind="property" type={`number`} default={`5000`}   />
+
+How long to buffer events for in milliseconds before executing the handler. This allows
+us to efficiently batch calls to the Stellate Purge API.
+### handler
+
+<MemberInfo kind="property" type={`(handlerArgs: {         events: Event[];         stellateService: <a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a>;         injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>;     }) =&#62; void | Promise&#60;void&#62;`}   />
+
+The function to invoke when the specified event is published. This function should use the
+<a href='/reference/core-plugins/stellate-plugin/stellate-service#stellateservice'>StellateService</a> instance to call the Stellate Purge API.
+
+
+</div>

package/docs/reference/core-plugins/stellate-plugin/stellate-plugin-options.md

@@ -0,0 +1,65 @@
+---
+title: "StellatePluginOptions"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## StellatePluginOptions
+
+<GenerationInfo sourceFile="packages/stellate-plugin/src/types.ts" sourceLine="9" packageName="@vendure/stellate-plugin" />
+
+Configuration options for the StellatePlugin.
+
+```ts title="Signature"
+interface StellatePluginOptions {
+    serviceName: string;
+    apiToken: string;
+    purgeRules: PurgeRule[];
+    defaultBufferTimeMs?: number;
+    devMode?: boolean;
+    debugLogging?: boolean;
+}
+```
+
+<div className="members-wrapper">
+
+### serviceName
+
+<MemberInfo kind="property" type={`string`}   />
+
+The Stellate service name, i.e. `<service-name>.stellate.sh`
+### apiToken
+
+<MemberInfo kind="property" type={`string`}   />
+
+The Stellate Purging API token. For instructions on how to generate the token,
+see the [Stellate docs](https://docs.stellate.co/docs/purging-api#authentication)
+### purgeRules
+
+<MemberInfo kind="property" type={`<a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a>[]`}   />
+
+An array of <a href='/reference/core-plugins/stellate-plugin/purge-rule#purgerule'>PurgeRule</a> instances which are used to define how the plugin will
+respond to Vendure events in order to trigger calls to the Stellate Purging API.
+### defaultBufferTimeMs
+
+<MemberInfo kind="property" type={`number`} default={`2000`}   />
+
+When events are published, the PurgeRules will buffer those events in order to efficiently
+batch requests to the Stellate Purging API. You may wish to change the default, e.g. if you are
+running in a serverless environment and cannot introduce pauses after the main request has completed.
+### devMode
+
+<MemberInfo kind="property" type={`boolean`} default={`false`}   />
+
+When set to `true`, calls will not be made to the Stellate Purge API.
+### debugLogging
+
+<MemberInfo kind="property" type={`boolean`} default={`false`}   />
+
+If set to true, the plugin will log the calls that would be made
+to the Stellate Purge API. Note, this generates a
+lot of debug-level logging.
+
+
+</div>