docs(typescript): API reference master

sdks/typescript/api/README.mdx

@@ -4,7 +4,7 @@ Auto-generated reference for [`resq-software/npm`](https://github.com/resq-softw
 
 ## Packages
 
-- `@resq-sw/analytics` — `v0.3.0`
+- `@resq-sw/analytics` — `v0.4.0`
 - `@resq-sw/decorators` — `v0.1.1`
 - `@resq-sw/dsa` — `v0.1.0`
 - `@resq-sw/http` — `v0.1.1`

sdks/typescript/api/analytics/index/classes/Analytics.md

@@ -1,6 +1,6 @@
 # Class: Analytics
 
-Defined in: [index.ts:111](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L111)
+Defined in: [index.ts:111](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L111)
 
 ## Constructors
 
@@ -20,7 +20,7 @@ Defined in: [index.ts:111](https://github.com/resq-software/npm/blob/f2ab5fc82f4
 
 > **get** **config**(): `Readonly`\<[`AnalyticsConfig`](../interfaces/AnalyticsConfig)\> \| `null`
 
-Defined in: [index.ts:116](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L116)
+Defined in: [index.ts:116](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L116)
 
 ##### Returns
 
@@ -34,7 +34,7 @@ Defined in: [index.ts:116](https://github.com/resq-software/npm/blob/f2ab5fc82f4
 
 > **get** **posthog**(): `PostHog` \| `null`
 
-Defined in: [index.ts:120](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L120)
+Defined in: [index.ts:120](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L120)
 
 ##### Returns
 
@@ -46,7 +46,7 @@ Defined in: [index.ts:120](https://github.com/resq-software/npm/blob/f2ab5fc82f4
 
 > **identify**(`userId`, `traits?`): `void`
 
-Defined in: [index.ts:181](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L181)
+Defined in: [index.ts:181](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L181)
 
 #### Parameters
 
@@ -68,7 +68,7 @@ Defined in: [index.ts:181](https://github.com/resq-software/npm/blob/f2ab5fc82f4
 
 > **init**(`config`): `Promise`\<`void`\>
 
-Defined in: [index.ts:124](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L124)
+Defined in: [index.ts:124](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L124)
 
 #### Parameters
 
@@ -86,7 +86,7 @@ Defined in: [index.ts:124](https://github.com/resq-software/npm/blob/f2ab5fc82f4
 
 > **pageview**(`url?`): `void`
 
-Defined in: [index.ts:211](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L211)
+Defined in: [index.ts:211](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L211)
 
 Manually emit a pageview. Most consumers do **not** need to call this:
 PostHog's `capture_pageview: "history_change"` (set in init) auto-captures
@@ -110,7 +110,7 @@ for first-paint pageviews before init has resolved.
 
 > **reset**(): `void`
 
-Defined in: [index.ts:194](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L194)
+Defined in: [index.ts:194](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L194)
 
 #### Returns
 
@@ -122,7 +122,7 @@ Defined in: [index.ts:194](https://github.com/resq-software/npm/blob/f2ab5fc82f4
 
 > **track**\<`E`\>(`event`, `properties?`): `void`
 
-Defined in: [index.ts:166](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L166)
+Defined in: [index.ts:166](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L166)
 
 #### Type Parameters
 

sdks/typescript/api/analytics/index/functions/identify.md

@@ -2,7 +2,7 @@
 
 > **identify**(`userId`, `traits?`): `void`
 
-Defined in: [index.ts:226](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L226)
+Defined in: [index.ts:226](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L226)
 
 ## Parameters
 

sdks/typescript/api/analytics/index/functions/inferCookieDomain.md

@@ -2,7 +2,7 @@
 
 > **inferCookieDomain**(`domains`): `string` \| `undefined`
 
-Defined in: [index.ts:243](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L243)
+Defined in: [index.ts:243](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L243)
 
 ## Parameters
 

sdks/typescript/api/analytics/index/functions/initAnalytics.md

@@ -2,7 +2,7 @@
 
 > **initAnalytics**(`config`): `Promise`\<`void`\>
 
-Defined in: [index.ts:222](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L222)
+Defined in: [index.ts:222](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L222)
 
 ## Parameters
 

sdks/typescript/api/analytics/index/functions/pageview.md

@@ -2,7 +2,7 @@
 
 > **pageview**(`url?`): `void`
 
-Defined in: [index.ts:231](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L231)
+Defined in: [index.ts:231](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L231)
 
 ## Parameters
 

sdks/typescript/api/analytics/index/functions/reset.md

@@ -2,7 +2,7 @@
 
 > **reset**(): `void`
 
-Defined in: [index.ts:229](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L229)
+Defined in: [index.ts:229](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L229)
 
 ## Returns
 

sdks/typescript/api/analytics/index/interfaces/AnalyticsConfig.md

@@ -1,43 +1,43 @@
 # Interface: AnalyticsConfig
 
-Defined in: [index.ts:50](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L50)
+Defined in: [index.ts:50](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L50)
 
 ## Properties
 
 ### cookieDomain?
 
 > `optional` **cookieDomain?**: `string`
 
-Defined in: [index.ts:53](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L53)
+Defined in: [index.ts:53](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L53)
 
 ***
 
 ### debug?
 
 > `optional` **debug?**: `boolean`
 
-Defined in: [index.ts:55](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L55)
+Defined in: [index.ts:55](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L55)
 
 ***
 
 ### disabled?
 
 > `optional` **disabled?**: `boolean`
 
-Defined in: [index.ts:54](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L54)
+Defined in: [index.ts:54](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L54)
 
 ***
 
 ### ga4?
 
 > `optional` **ga4?**: [`GA4ProviderConfig`](./GA4ProviderConfig)
 
-Defined in: [index.ts:52](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L52)
+Defined in: [index.ts:52](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L52)
 
 ***
 
 ### posthog?
 
 > `optional` **posthog?**: [`PostHogProviderConfig`](./PostHogProviderConfig)
 
-Defined in: [index.ts:51](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L51)
+Defined in: [index.ts:51](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L51)

sdks/typescript/api/analytics/index/interfaces/AnalyticsEvents.md

@@ -1,6 +1,6 @@
 # Interface: AnalyticsEvents
 
-Defined in: [index.ts:34](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L34)
+Defined in: [index.ts:34](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L34)
 
 Augmentable typed event registry. Consumers extend this via module
 augmentation to get type-safe `track()` calls:

sdks/typescript/api/analytics/index/interfaces/GA4ProviderConfig.md

@@ -1,19 +1,19 @@
 # Interface: GA4ProviderConfig
 
-Defined in: [index.ts:45](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L45)
+Defined in: [index.ts:45](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L45)
 
 ## Properties
 
 ### domains?
 
 > `optional` **domains?**: `string`[]
 
-Defined in: [index.ts:47](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L47)
+Defined in: [index.ts:47](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L47)
 
 ***
 
 ### measurementId
 
 > **measurementId**: `string`
 
-Defined in: [index.ts:46](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L46)
+Defined in: [index.ts:46](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L46)

sdks/typescript/api/analytics/index/interfaces/PostHogProviderConfig.md

@@ -1,35 +1,35 @@
 # Interface: PostHogProviderConfig
 
-Defined in: [index.ts:38](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L38)
+Defined in: [index.ts:38](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L38)
 
 ## Properties
 
 ### host?
 
 > `optional` **host?**: `string`
 
-Defined in: [index.ts:40](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L40)
+Defined in: [index.ts:40](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L40)
 
 ***
 
 ### key
 
 > **key**: `string`
 
-Defined in: [index.ts:39](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L39)
+Defined in: [index.ts:39](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L39)
 
 ***
 
 ### options?
 
 > `optional` **options?**: `Partial`\<`PostHogConfig`\>
 
-Defined in: [index.ts:42](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L42)
+Defined in: [index.ts:42](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L42)
 
 ***
 
 ### uiHost?
 
 > `optional` **uiHost?**: `string`
 
-Defined in: [index.ts:41](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L41)
+Defined in: [index.ts:41](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L41)

sdks/typescript/api/analytics/index/variables/analytics.md

@@ -2,4 +2,4 @@
 
 > `const` **analytics**: [`Analytics`](../classes/Analytics)
 
-Defined in: [index.ts:220](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L220)
+Defined in: [index.ts:220](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L220)

sdks/typescript/api/analytics/index/variables/track.md

@@ -2,4 +2,4 @@
 
 > `const` **track**: [`Analytics`](../classes/Analytics)\[`"track"`\]
 
-Defined in: [index.ts:224](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/index.ts#L224)
+Defined in: [index.ts:224](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/index.ts#L224)

sdks/typescript/api/analytics/next/functions/ga4Stream.md

@@ -2,18 +2,34 @@
 
 > **ga4Stream**(`measurementId`, `domains?`): [`GA4ProviderConfig`](../../index/interfaces/GA4ProviderConfig)
 
-Defined in: [next/index.ts:74](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/next/index.ts#L74)
+Defined in: [next/index.ts:139](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/next/index.ts#L139)
+
+Build a [GA4ProviderConfig](../../index/interfaces/GA4ProviderConfig) with cross-subdomain linker
+domains. Drop into `AnalyticsConfig.ga4`:
+
+```ts
+const config: AnalyticsConfig = {
+  posthog: { ... },
+  ga4: ga4Stream("G-XXXXXXX", ["resq.software", "research.resq.software", "viz.resq.software"]),
+};
+```
 
 ## Parameters
 
 ### measurementId
 
 `string`
 
+GA4 Measurement ID (`G-…`).
+
 ### domains?
 
 `string`[]
 
+Domain allow-list passed to gtag's `linker.domains`,
+  so cross-subdomain navigation no longer counts as referral
+  traffic.
+
 ## Returns
 
 [`GA4ProviderConfig`](../../index/interfaces/GA4ProviderConfig)

sdks/typescript/api/analytics/next/functions/withAnalyticsRewrites.md

@@ -2,14 +2,31 @@
 
 > **withAnalyticsRewrites**\<`T`\>(`nextConfig`, `options?`): `T`
 
-Defined in: [next/index.ts:41](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/next/index.ts#L41)
+Defined in: [next/index.ts:90](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/next/index.ts#L90)
+
+Wrap a Next.js config to add reverse-proxy rewrites for
+`@resq-sw/analytics`.
+
+Adds two rules to the `beforeFiles` rewrite array:
+
+1. `/<prefix>/static/:path* → assetsUpstream/static/:path*`
+   (PostHog snippet bundle).
+2. `/<prefix>/:path*        → upstream/:path*`
+   (everything else: capture, decide, `/e/`).
+
+Pre-existing user-defined rewrites are preserved — the proxy
+rules go *first* so they win when paths overlap. Also forces
+`skipTrailingSlashRedirect: true`, which is required for the
+proxy to work reliably across `/ingest` and `/ingest/`.
 
 ## Type Parameters
 
 ### T
 
 `T` *extends* `MinimalNextConfig`
 
+The user's full `next.config.{js,ts}` type.
+
 ## Parameters
 
 ### nextConfig
@@ -23,3 +40,14 @@ Defined in: [next/index.ts:41](https://github.com/resq-software/npm/blob/f2ab5fc
 ## Returns
 
 `T`
+
+## Example
+
+```ts
+import { withAnalyticsRewrites } from "@resq-sw/analytics/next";
+
+export default withAnalyticsRewrites({
+  reactStrictMode: true,
+  // ...rest of your config
+});
+```

sdks/typescript/api/analytics/next/interfaces/AnalyticsRewriteOptions.md

@@ -1,27 +1,39 @@
 # Interface: AnalyticsRewriteOptions
 
-Defined in: [next/index.ts:21](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/next/index.ts#L21)
+Defined in: [next/index.ts:39](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/next/index.ts#L39)
+
+Options for [withAnalyticsRewrites](../functions/withAnalyticsRewrites).
+
+Defaults are tuned for PostHog's US ingestion endpoints; override
+`upstream` / `assetsUpstream` for EU regions or self-hosted
+deployments.
 
 ## Properties
 
 ### assetsUpstream?
 
 > `optional` **assetsUpstream?**: `string`
 
-Defined in: [next/index.ts:24](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/next/index.ts#L24)
+Defined in: [next/index.ts:45](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/next/index.ts#L45)
+
+PostHog static-assets endpoint. Default `"https://us-assets.i.posthog.com"`.
 
 ***
 
 ### prefix?
 
 > `optional` **prefix?**: `string`
 
-Defined in: [next/index.ts:22](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/next/index.ts#L22)
+Defined in: [next/index.ts:41](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/next/index.ts#L41)
+
+Local path prefix that proxies to PostHog. Default `"/ingest"`.
 
 ***
 
 ### upstream?
 
 > `optional` **upstream?**: `string`
 
-Defined in: [next/index.ts:23](https://github.com/resq-software/npm/blob/f2ab5fc82f4f501236bfdc25d86881be8e1fb643/packages/analytics/src/next/index.ts#L23)
+Defined in: [next/index.ts:43](https://github.com/resq-software/npm/blob/fe2e20ae9db8398a0db1e3218edaabb3cf7004d6/packages/analytics/src/next/index.ts#L43)
+
+PostHog ingestion endpoint. Default `"https://us.i.posthog.com"`.