@openpolicy/sdk 0.0.18 → 0.0.20

package/skills/annotate-third-parties/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: annotate-third-parties
+description: >
+  Mark third-party service dependencies in source code using thirdParty() so
+  the autoCollect() Vite plugin can populate the thirdParties sentinel for the
+  privacy policy config. Covers manual annotation, usePackageJson auto-detection
+  from the KNOWN_PACKAGES registry, combining both approaches, and the Providers
+  preset as a static alternative.
+type: core
+library: openpolicy
+library_version: "0.0.19"
+requires:
+  - openpolicy/vite-setup
+sources:
+  - jamiedavenport/openpolicy:packages/sdk/src/third-parties.ts
+  - jamiedavenport/openpolicy:packages/vite-auto-collect/src/known-packages.ts
+---
+
+This skill builds on openpolicy/vite-setup. Read it first.
+
+## How It Works
+
+`thirdParty()` is a **runtime no-op**. It is a build-time marker — `autoCollect()` scans source files statically via `oxc-parser` and extracts the three string literal arguments. The plugin then populates the `thirdParties` sentinel exported from `@openpolicy/sdk`. Without the plugin, `thirdParty()` calls have no effect whatsoever.
+
+The populated sentinel must be spread into `privacy.thirdParties` in the config file. Without the spread, the plugin output is discarded and the policy renders with no third parties listed.
+
+## Setup
+
+Three moving parts must all be in place:
+
+**1. `vite.config.ts` — enable the plugin**
+
+```ts
+import { defineConfig } from "vite";
+import { autoCollect } from "@openpolicy/vite-auto-collect";
+
+export default defineConfig({
+  plugins: [
+    autoCollect({
+      thirdParties: { usePackageJson: true }, // optional — see below
+    }),
+  ],
+});
+```
+
+**2. Source file — annotate next to the usage**
+
+```ts
+import { thirdParty } from "@openpolicy/sdk";
+
+// Place next to where you initialise or use the third-party SDK
+thirdParty("Stripe", "Payment processing", "https://stripe.com/privacy");
+
+// ... rest of your Stripe integration
+```
+
+**3. `openpolicy.ts` — spread the sentinel into config**
+
+```ts
+import { defineConfig, thirdParties } from "@openpolicy/sdk";
+
+export default defineConfig({
+  company: {
+    name: "Acme",
+    legalName: "Acme, Inc.",
+    address: "123 Main St, San Francisco, CA 94105",
+    contact: "privacy@acme.com",
+  },
+  privacy: {
+    effectiveDate: "2026-01-01",
+    thirdParties: [...thirdParties],
+  },
+});
+```
+
+## Core Patterns
+
+### 1. Manual thirdParty() annotation
+
+Call `thirdParty(name, purpose, policyUrl)` with three string literals next to wherever you initialise the third-party integration. All three arguments must be string literals — dynamic values are silently skipped by the static analyser.
+
+```ts
+import { thirdParty } from "@openpolicy/sdk";
+
+// Correct: all string literals
+thirdParty("Intercom", "Customer messaging", "https://www.intercom.com/legal/privacy");
+
+// Wrong: variable — silently skipped at build time
+const name = "Intercom";
+thirdParty(name, "Customer messaging", "https://www.intercom.com/legal/privacy");
+```
+
+Deduplication is by `name` — the first occurrence wins when files are walked in sorted alphabetical order. Calling `thirdParty()` with the same name from multiple files is safe.
+
+### 2. usePackageJson auto-detection
+
+`autoCollect({ thirdParties: { usePackageJson: true } })` reads `package.json` at build time and cross-references every entry in `dependencies` and `devDependencies` against the built-in KNOWN_PACKAGES registry. Matched packages are merged into `thirdParties` automatically, with deduplication by service name.
+
+This is the fastest way to cover common services (Stripe, Sentry, PostHog, Vercel, etc.) without any source annotations.
+
+```ts
+// vite.config.ts
+autoCollect({ thirdParties: { usePackageJson: true } })
+```
+
+See [references/known-packages.md](references/known-packages.md) for the full list of ~30 auto-detected packages.
+
+### 3. Combining both approaches
+
+`thirdParty()` annotations and `usePackageJson` are merged at build time. The plugin deduplicates by service name — `thirdParty()` entries from source files are added first (sorted file order), then package.json detections fill in any remaining services not already seen.
+
+Use this combination when:
+- Most services are covered by the KNOWN_PACKAGES registry (`usePackageJson: true`)
+- A few services are not in the registry and need explicit `thirdParty()` calls
+
+```ts
+// vite.config.ts
+autoCollect({ thirdParties: { usePackageJson: true } })
+
+// src/lib/custom-analytics.ts
+import { thirdParty } from "@openpolicy/sdk";
+thirdParty("Fathom Analytics", "Privacy-friendly web analytics", "https://usefathom.com/privacy");
+```
+
+```ts
+// openpolicy.ts — one spread covers both sources
+import { defineConfig, thirdParties } from "@openpolicy/sdk";
+
+export default defineConfig({
+  privacy: {
+    thirdParties: [...thirdParties],
+  },
+});
+```
+
+### 4. Providers presets as a static alternative
+
+`Providers` from `@openpolicy/sdk` is a collection of pre-filled third-party objects for common services. Use this when you want to declare third parties statically in `openpolicy.ts` without any source annotations or plugin scanning.
+
+```ts
+import { defineConfig, Providers } from "@openpolicy/sdk";
+
+export default defineConfig({
+  privacy: {
+    thirdParties: [
+      Providers.Stripe,
+      Providers.Sentry,
+      Providers.Vercel,
+      { name: "Custom Service", purpose: "Internal logging", policyUrl: "https://example.com/privacy" },
+    ],
+  },
+});
+```
+
+Available presets: `Stripe`, `Paddle`, `LemonSqueezy`, `PayPal`, `GoogleAnalytics`, `PostHog`, `Plausible`, `Mixpanel`, `Vercel`, `Cloudflare`, `AWS`, `Auth0`, `Clerk`, `Resend`, `Postmark`, `SendGrid`, `Loops`, `Sentry`, `Datadog`.
+
+Note: when using `Providers` statically, you can still spread `thirdParties` alongside it to capture any additional auto-collected services:
+
+```ts
+privacy: {
+  thirdParties: [...thirdParties, Providers.Cloudflare],
+}
+```
+
+## Common Mistakes
+
+### HIGH — Using thirdParty() without the autoCollect() plugin and expecting a runtime effect
+
+`thirdParty()` is defined as a no-op function that immediately returns `undefined`. It has no runtime behaviour. The only way it produces output in the policy is when `autoCollect()` is present in `vite.config.ts` and scans the file at build time.
+
+```ts
+// WRONG: calling thirdParty() and expecting it to affect the policy at runtime
+import { thirdParty } from "@openpolicy/sdk";
+thirdParty("Stripe", "Payment processing", "https://stripe.com/privacy");
+// Without autoCollect() in vite.config.ts, this does nothing
+```
+
+```ts
+// Correct: autoCollect() in vite.config.ts is the required prerequisite
+// vite.config.ts
+import { autoCollect } from "@openpolicy/vite-auto-collect";
+export default defineConfig({ plugins: [autoCollect()] });
+
+// src/lib/stripe.ts — scanned at build time by the plugin
+import { thirdParty } from "@openpolicy/sdk";
+thirdParty("Stripe", "Payment processing", "https://stripe.com/privacy");
+```
+
+### HIGH — Not spreading thirdParties sentinel into privacy.thirdParties
+
+Even when `autoCollect()` scans the source and populates the sentinel, the populated value is discarded unless it is imported and spread into `privacy.thirdParties` in the config. The privacy policy then renders with an empty third-party section, which may be legally invalid.
+
+```ts
+// WRONG: thirdParties not imported or spread
+export default defineConfig({
+  privacy: {
+    thirdParties: [], // static empty array, discards plugin output
+  },
+});
+```
+
+```ts
+// Correct
+import { defineConfig, thirdParties } from "@openpolicy/sdk";
+
+export default defineConfig({
+  privacy: {
+    thirdParties: [...thirdParties],
+    // or combine with static entries:
+    // thirdParties: [...thirdParties, Providers.Cloudflare],
+  },
+});
+```
+
+### MEDIUM — Not enabling usePackageJson when known packages are used
+
+The KNOWN_PACKAGES registry covers ~30 common npm packages. Without `usePackageJson: true`, packages like `@sentry/browser`, `posthog-js`, or `@stripe/stripe-js` are not auto-detected and must each be annotated manually with `thirdParty()`. Enabling the option costs nothing and eliminates this annotation burden for any covered package.
+
+```ts
+// WRONG: usePackageJson not enabled — known packages not auto-detected
+autoCollect()
+```
+
+```ts
+// Correct
+autoCollect({ thirdParties: { usePackageJson: true } })
+```
+
+## References
+
+- [Known packages registry](references/known-packages.md) — full table of npm packages auto-detected by `usePackageJson: true`
+- `packages/sdk/src/third-parties.ts` — thirdParty() implementation (runtime no-op)
+- `packages/sdk/src/providers.ts` — Providers preset objects
+- `packages/sdk/src/auto-collected.ts` — thirdParties sentinel definition
+- `packages/vite-auto-collect/src/index.ts` — autoCollect() plugin, AutoCollectOptions type
+- `packages/vite-auto-collect/src/analyse.ts` — static AST extraction logic
+- `packages/vite-auto-collect/src/known-packages.ts` — KNOWN_PACKAGES registry source

package/skills/annotate-third-parties/references/known-packages.md

@@ -0,0 +1,37 @@
+# Known Packages Registry
+
+These npm package names are auto-detected when `usePackageJson: true` is set in `autoCollect()`. The plugin reads `dependencies` and `devDependencies` from the project root `package.json` and matches entries against this registry. Multiple package names can map to the same service — deduplication is by service name, first match wins.
+
+| npm package | Service name | Purpose |
+|---|---|---|
+| `stripe` | Stripe | Payment processing |
+| `@stripe/stripe-js` | Stripe | Payment processing |
+| `braintree` | Braintree | Payment processing |
+| `@braintree/browser-drop-in` | Braintree | Payment processing |
+| `@sentry/browser` | Sentry | Error tracking |
+| `@sentry/node` | Sentry | Error tracking |
+| `@sentry/nextjs` | Sentry | Error tracking |
+| `@sentry/react` | Sentry | Error tracking |
+| `@sentry/vue` | Sentry | Error tracking |
+| `@datadog/browser-rum` | Datadog | Monitoring |
+| `dd-trace` | Datadog | Monitoring |
+| `posthog-js` | PostHog | Product analytics |
+| `posthog-node` | PostHog | Product analytics |
+| `mixpanel-browser` | Mixpanel | Product analytics |
+| `@segment/analytics-next` | Segment | Customer data platform |
+| `@amplitude/analytics-browser` | Amplitude | Product analytics |
+| `amplitude-js` | Amplitude | Product analytics |
+| `@vercel/analytics` | Vercel Analytics | Web analytics |
+| `plausible-tracker` | Plausible | Web analytics |
+| `logrocket` | LogRocket | Session recording |
+| `@hotjar/browser` | Hotjar | Session recording |
+| `resend` | Resend | Transactional email |
+| `@sendgrid/mail` | SendGrid | Transactional email |
+| `intercom-client` | Intercom | Customer messaging |
+| `@intercom/messenger-js-sdk` | Intercom | Customer messaging |
+
+## Services not in the registry
+
+For services not listed here, use `thirdParty()` source annotations or the `Providers` preset constants from `@openpolicy/sdk`. See the main skill file for examples.
+
+The registry source is at `packages/vite-auto-collect/src/known-packages.ts`.

package/skills/define-config/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: define-config
+description: >
+  Writing the defineConfig() object for OpenPolicyConfig — privacy, terms, cookie — including all field types, jurisdiction requirements, and preset constants from @openpolicy/sdk.
+type: core
+library: openpolicy
+library_version: "0.0.19"
+sources:
+  - jamiedavenport/openpolicy:packages/core/src/types.ts
+  - jamiedavenport/openpolicy:packages/sdk/src/constants.ts
+---
+
+# openpolicy/define-config
+
+Write and maintain the `defineConfig()` call in `openpolicy.ts`. The function is an identity function used as a type marker — it accepts `OpenPolicyConfig` and returns it unchanged.
+
+## Setup
+
+Minimal config with privacy policy:
+
+```ts
+// openpolicy.ts
+import { defineConfig, dataCollected, thirdParties } from "@openpolicy/sdk";
+
+export default defineConfig({
+  company: {
+    name: "Acme",
+    legalName: "Acme, Inc.",
+    address: "123 Main St, San Francisco, CA 94105",
+    contact: "privacy@acme.com",
+  },
+  privacy: {
+    effectiveDate: "2026-01-01",
+    dataCollected: { ...dataCollected },
+    legalBasis: "legitimate_interests",
+    retention: { "Account Information": "Until account deletion" },
+    cookies: { essential: true, analytics: false, marketing: false },
+    thirdParties: [...thirdParties],
+    userRights: ["access", "erasure"],
+    jurisdictions: ["us"],
+  },
+});
+```
+
+`company` is declared once at the top level — do not repeat it inside `privacy`, `terms`, or `cookie`.
+
+## Core Patterns
+
+### 1. Privacy config with GDPR
+
+Use `Compliance.GDPR` to spread the required `jurisdictions`, `legalBasis`, and `userRights` values in one step:
+
+```ts
+import {
+  defineConfig,
+  Compliance,
+  DataCategories,
+  Retention,
+  Providers,
+  dataCollected,
+  thirdParties,
+} from "@openpolicy/sdk";
+
+export default defineConfig({
+  company: {
+    name: "Acme",
+    legalName: "Acme, Inc.",
+    address: "123 Main St, San Francisco, CA 94105",
+    contact: "privacy@acme.com",
+  },
+  privacy: {
+    effectiveDate: "2026-01-01",
+    ...Compliance.GDPR,
+    dataCollected: {
+      ...dataCollected,
+      ...DataCategories.AccountInfo,
+      ...DataCategories.UsageData,
+    },
+    retention: {
+      "Account Information": Retention.UntilAccountDeletion,
+      "Usage Data": Retention.NinetyDays,
+    },
+    cookies: { essential: true, analytics: true, marketing: false },
+    thirdParties: [...thirdParties, Providers.Stripe, Providers.PostHog],
+    children: { underAge: 13 },
+  },
+});
+```
+
+`Compliance.GDPR` expands to `{ jurisdictions: ["eu"], legalBasis: ["legitimate_interests"], userRights: ["access", "rectification", "erasure", "portability", "restriction", "objection"] }`.
+
+### 2. Terms of service config
+
+`governingLaw` is required — validation throws if absent.
+
+```ts
+export default defineConfig({
+  company: { ... },
+  terms: {
+    effectiveDate: "2026-01-01",
+    acceptance: { methods: ["using the service", "creating an account"] },
+    governingLaw: { jurisdiction: "Delaware, USA" },
+    eligibility: { minimumAge: 18 },
+    accounts: {
+      registrationRequired: true,
+      userResponsibleForCredentials: true,
+      companyCanTerminate: true,
+    },
+    disclaimers: { serviceProvidedAsIs: true, noWarranties: true },
+    limitationOfLiability: {
+      excludesIndirectDamages: true,
+      liabilityCap: "fees paid in the last 12 months",
+    },
+    termination: {
+      companyCanTerminate: true,
+      userCanTerminate: true,
+      effectOfTermination: "All licenses granted to the user terminate immediately.",
+    },
+    disputeResolution: {
+      method: "arbitration",
+      venue: "San Francisco, CA",
+      classActionWaiver: true,
+    },
+  },
+});
+```
+
+All fields other than `effectiveDate`, `acceptance`, and `governingLaw` are optional. Include sections only when the corresponding policy content applies. See [references/terms-config.md](./references/terms-config.md) for the full field table.
+
+### 3. Using Compliance presets
+
+`Compliance.GDPR` and `Compliance.CCPA` are objects safe to spread into `privacy`:
+
+```ts
+import { Compliance } from "@openpolicy/sdk";
+
+// GDPR only
+privacy: { ...Compliance.GDPR, ... }
+
+// Both (array values merge correctly via spread — userRights and jurisdictions union)
+privacy: {
+  ...Compliance.GDPR,
+  jurisdictions: [...Compliance.GDPR.jurisdictions, ...Compliance.CCPA.jurisdictions],
+  userRights: [...Compliance.GDPR.userRights, ...Compliance.CCPA.userRights],
+  ...
+}
+```
+
+`Compliance.CCPA` does not include `legalBasis` — it provides only `jurisdictions: ["ca"]` and `userRights: ["access", "erasure", "opt_out_sale", "non_discrimination"]`.
+
+Available preset groups from `@openpolicy/sdk`:
+
+| Export | Content |
+|---|---|
+| `DataCategories` | Named `dataCollected` entries (AccountInfo, SessionData, PaymentInfo, UsageData, DeviceInfo, LocationData, Communications) |
+| `Retention` | Retention period strings (UntilAccountDeletion, ThirtyDays, NinetyDays, OneYear, ThreeYears, AsRequiredByLaw, …) |
+| `Rights` | `UserRight` string constants (Access, Rectification, Erasure, …) |
+| `LegalBases` | `LegalBasis` string constants (Consent, Contract, LegitimateInterests, …) |
+| `Compliance` | Preset bundles: `GDPR`, `CCPA` |
+| `Providers` | Named third-party descriptors: Stripe, PostHog, Vercel, Sentry, Clerk, Resend, … |
+
+### 4. Cookie config
+
+```ts
+export default defineConfig({
+  company: { ... },
+  cookie: {
+    effectiveDate: "2026-01-01",
+    cookies: { essential: true, analytics: true, marketing: false },
+    jurisdictions: ["eu", "us"],
+    consentMechanism: {
+      hasBanner: true,
+      hasPreferencePanel: true,
+      canWithdraw: true,
+    },
+    trackingTechnologies: ["localStorage", "sessionStorage", "cookies"],
+    thirdParties: [Providers.GoogleAnalytics, Providers.Cloudflare],
+  },
+});
+```
+
+`CookiePolicyCookies` requires `essential: boolean` — all other keys are `boolean` and are treated as additional cookie categories.
+
+## Common Mistakes
+
+### HIGH — Using standalone PrivacyPolicyConfig instead of nested OpenPolicyConfig
+
+Wrong:
+```ts
+// WRONG: standalone shape, company repeated inside the policy object
+import type { PrivacyPolicyConfig } from "@openpolicy/sdk";
+
+const config: PrivacyPolicyConfig = {
+  company: { name: "Acme", legalName: "Acme, Inc.", address: "...", contact: "..." },
+  effectiveDate: "2026-01-01",
+  dataCollected: {},
+  legalBasis: "consent",
+  retention: {},
+  cookies: { essential: true, analytics: false, marketing: false },
+  thirdParties: [],
+  userRights: [],
+  jurisdictions: [],
+};
+```
+
+Correct:
+```ts
+// correct: nested OpenPolicyConfig via defineConfig()
+import { defineConfig } from "@openpolicy/sdk";
+
+export default defineConfig({
+  company: { name: "Acme", legalName: "Acme, Inc.", address: "...", contact: "privacy@acme.com" },
+  privacy: {
+    effectiveDate: "2026-01-01",
+    dataCollected: {},
+    legalBasis: "consent",
+    retention: {},
+    cookies: { essential: true, analytics: false, marketing: false },
+    thirdParties: [],
+    userRights: [],
+    jurisdictions: [],
+  },
+});
+```
+
+React components and the autoCollect pipeline read from `OpenPolicyConfig`; the standalone policy types are internal shapes not consumed by the rendering layer.
+
+Source: `packages/core/src/types.ts`
+
+---
+
+### HIGH — Omitting governingLaw from terms of service
+
+Wrong:
+```ts
+// WRONG: governingLaw missing — validation throws at compile time
+terms: {
+  effectiveDate: "2026-01-01",
+  acceptance: { methods: ["using the service"] },
+}
+```
+
+Correct:
+```ts
+terms: {
+  effectiveDate: "2026-01-01",
+  acceptance: { methods: ["using the service"] },
+  governingLaw: { jurisdiction: "Delaware, USA" },
+}
+```
+
+`governingLaw` is a required field on `TermsOfServiceConfig`. `validateTermsOfService()` emits a fatal error if `governingLaw.jurisdiction` is absent or empty. TypeScript will catch this at authoring time only if the object is typed as `Omit<TermsOfServiceConfig, "company">`.
+
+Source: `packages/core/src/validate-terms.ts`
+
+---
+
+### MEDIUM — Not specifying jurisdictions — GDPR/CCPA sections silently absent
+
+Wrong:
+```ts
+// WRONG: jurisdictions missing — legalBasis section and GDPR/CCPA content will not appear
+privacy: {
+  legalBasis: "legitimate_interests",
+  userRights: ["access", "erasure"],
+  // jurisdictions omitted
+}
+```
+
+Correct:
+```ts
+privacy: {
+  legalBasis: "legitimate_interests",
+  userRights: ["access", "erasure"],
+  jurisdictions: ["eu", "us"],
+}
+```
+
+Section builders for GDPR (`eu`) and CCPA (`ca`) content check `config.jurisdictions` before generating output. Omitting `jurisdictions` (or passing an empty array) causes those sections to be silently skipped with no warning. `Compliance.GDPR` and `Compliance.CCPA` include the correct `jurisdictions` values when spread.
+
+Source: `packages/core/src/templates/privacy/`
+
+## Reference
+
+- [PrivacyPolicyConfig and CookiePolicyConfig field table](./references/privacy-config.md)
+- [TermsOfServiceConfig field table](./references/terms-config.md)