@openpolicy/sdk 0.0.19 → 0.0.20

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)

package/skills/define-config/references/privacy-config.md

@@ -0,0 +1,153 @@
+# PrivacyPolicyConfig Field Reference
+
+When used inside `defineConfig()`, `company` is omitted — it lives at the top level of `OpenPolicyConfig`. All other fields below are on `privacy: Omit<PrivacyPolicyConfig, "company">`.
+
+## PrivacyPolicyConfig
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `effectiveDate` | `string` | Yes | ISO date string (e.g. `"2026-01-01"`). Validation fails if empty. |
+| `dataCollected` | `Record<string, string[]>` | Yes | At least one entry required. Keys are category labels; values are arrays of data point labels. Use `DataCategories.*` presets or spread `dataCollected` sentinel. |
+| `legalBasis` | `LegalBasis \| LegalBasis[]` | Yes (GDPR) | Required when `"eu"` is in `jurisdictions`. Accepts a single value or array. |
+| `retention` | `Record<string, string>` | Yes | Keys should match `dataCollected` categories. Use `Retention.*` preset strings. |
+| `cookies` | `{ essential: boolean; analytics: boolean; marketing: boolean }` | Yes | All three booleans required. Drives cookie policy sections. |
+| `thirdParties` | `{ name: string; purpose: string; policyUrl?: string }[]` | Yes | Can be empty array. Use `Providers.*` presets or spread `thirdParties` sentinel. |
+| `userRights` | `UserRight[]` | Yes | Empty array triggers a warning. GDPR recommends 6 rights; CCPA recommends 4. |
+| `jurisdictions` | `Jurisdiction[]` | Yes | Controls which jurisdiction-specific sections appear. See values below. |
+| `children` | `{ underAge: number; noticeUrl?: string }` | No | Include when service is directed at children. `underAge` must be a positive integer. |
+
+### LegalBasis values
+
+| Constant | String value |
+|---|---|
+| `LegalBases.Consent` | `"consent"` |
+| `LegalBases.Contract` | `"contract"` |
+| `LegalBases.LegalObligation` | `"legal_obligation"` |
+| `LegalBases.VitalInterests` | `"vital_interests"` |
+| `LegalBases.PublicTask` | `"public_task"` |
+| `LegalBases.LegitimateInterests` | `"legitimate_interests"` |
+
+### Jurisdiction values
+
+| Value | Region |
+|---|---|
+| `"us"` | United States |
+| `"eu"` | European Union (triggers GDPR sections) |
+| `"ca"` | California, USA (triggers CCPA sections) |
+| `"au"` | Australia |
+| `"nz"` | New Zealand |
+| `"other"` | Other / unspecified |
+
+### UserRight values
+
+| Constant | String value | Required by |
+|---|---|---|
+| `Rights.Access` | `"access"` | GDPR, CCPA |
+| `Rights.Rectification` | `"rectification"` | GDPR |
+| `Rights.Erasure` | `"erasure"` | GDPR, CCPA |
+| `Rights.Portability` | `"portability"` | GDPR |
+| `Rights.Restriction` | `"restriction"` | GDPR |
+| `Rights.Objection` | `"objection"` | GDPR |
+| `Rights.OptOutSale` | `"opt_out_sale"` | CCPA |
+| `Rights.NonDiscrimination` | `"non_discrimination"` | CCPA |
+
+### DataCategories presets
+
+Each entry is a `Record<string, string[]>` safe to spread into `dataCollected`:
+
+| Constant | Category label | Data points |
+|---|---|---|
+| `DataCategories.AccountInfo` | `"Account Information"` | Name, Email address |
+| `DataCategories.SessionData` | `"Session Data"` | IP address, User agent, Browser type |
+| `DataCategories.PaymentInfo` | `"Payment Information"` | Card last 4 digits, Billing name, Billing address |
+| `DataCategories.UsageData` | `"Usage Data"` | Pages visited, Features used, Time spent |
+| `DataCategories.DeviceInfo` | `"Device Information"` | Device type, Operating system, Browser version |
+| `DataCategories.LocationData` | `"Location Data"` | Country, City, Timezone |
+| `DataCategories.Communications` | `"Communications"` | Email content, Support tickets |
+
+### Retention presets
+
+| Constant | String value |
+|---|---|
+| `Retention.UntilAccountDeletion` | `"Until account deletion"` |
+| `Retention.UntilSessionExpiry` | `"Until session expiry"` |
+| `Retention.ThirtyDays` | `"30 days"` |
+| `Retention.NinetyDays` | `"90 days"` |
+| `Retention.OneYear` | `"1 year"` |
+| `Retention.ThreeYears` | `"3 years"` |
+| `Retention.AsRequiredByLaw` | `"As required by applicable law"` |
+
+### Providers presets
+
+Each entry is a `{ name: string; purpose: string; policyUrl: string }` safe to use in `thirdParties`:
+
+**Payments:** `Providers.Stripe`, `Providers.Paddle`, `Providers.LemonSqueezy`, `Providers.PayPal`
+
+**Analytics:** `Providers.GoogleAnalytics`, `Providers.PostHog`, `Providers.Plausible`, `Providers.Mixpanel`
+
+**Infrastructure:** `Providers.Vercel`, `Providers.Cloudflare`, `Providers.AWS`
+
+**Auth:** `Providers.Auth0`, `Providers.Clerk`
+
+**Email:** `Providers.Resend`, `Providers.Postmark`, `Providers.SendGrid`, `Providers.Loops`
+
+**Monitoring:** `Providers.Sentry`, `Providers.Datadog`
+
+### Compliance presets
+
+| Preset | Expands to |
+|---|---|
+| `Compliance.GDPR` | `{ jurisdictions: ["eu"], legalBasis: ["legitimate_interests"], userRights: ["access", "rectification", "erasure", "portability", "restriction", "objection"] }` |
+| `Compliance.CCPA` | `{ jurisdictions: ["ca"], userRights: ["access", "erasure", "opt_out_sale", "non_discrimination"] }` |
+
+### Validation behavior
+
+- `effectiveDate` empty → fatal error
+- `company.*` fields empty → fatal error per field
+- `dataCollected` has zero keys → fatal error
+- `userRights` empty → warning only
+- `"eu"` in jurisdictions + no `legalBasis` → fatal error
+- `"eu"` in jurisdictions + missing GDPR right → warning per right
+- `"ca"` in jurisdictions + missing CCPA right → warning per right
+- `children.underAge` ≤ 0 → fatal error
+
+Source: `packages/core/src/validate.ts`
+
+---
+
+## CookiePolicyConfig
+
+When used inside `defineConfig()`, supply as `cookie: Omit<CookiePolicyConfig, "company">`.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `effectiveDate` | `string` | Yes | ISO date string. |
+| `cookies` | `CookiePolicyCookies` | Yes | `essential: boolean` is required; all other keys are `boolean` and treated as additional cookie categories. |
+| `jurisdictions` | `Jurisdiction[]` | Yes | Same values as `PrivacyPolicyConfig.jurisdictions`. |
+| `thirdParties` | `{ name: string; purpose: string; policyUrl?: string }[]` | No | Use `Providers.*` presets. |
+| `trackingTechnologies` | `string[]` | No | e.g. `["cookies", "localStorage", "sessionStorage", "pixel"]` |
+| `consentMechanism` | `{ hasBanner: boolean; hasPreferencePanel: boolean; canWithdraw: boolean }` | No | Required when `"eu"` in jurisdictions for GDPR compliance. |
+
+### CookiePolicyCookies shape
+
+```ts
+type CookiePolicyCookies = {
+  essential: boolean;   // required
+  [key: string]: boolean; // additional categories
+};
+```
+
+Example with custom categories:
+
+```ts
+cookie: {
+  effectiveDate: "2026-01-01",
+  cookies: {
+    essential: true,
+    analytics: true,
+    marketing: false,
+    preferences: true,
+  },
+  jurisdictions: ["eu", "us"],
+}
+```

package/skills/define-config/references/terms-config.md

@@ -0,0 +1,130 @@
+# TermsOfServiceConfig Field Reference
+
+When used inside `defineConfig()`, supply as `terms: Omit<TermsOfServiceConfig, "company">`. `company` lives at the top level of `OpenPolicyConfig`.
+
+## Required fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `effectiveDate` | `string` | ISO date string. Validation fails if empty. |
+| `acceptance` | `{ methods: string[] }` | How users accept — e.g. `["using the service", "creating an account"]`. Warning if `methods` is empty. |
+| `governingLaw` | `{ jurisdiction: string }` | **Required.** Validation throws fatal error if `jurisdiction` is absent or empty. |
+
+## Optional sections
+
+All fields below are optional. Include only those that apply to the service. Omitting a field causes the corresponding policy section to be absent from the rendered document.
+
+| Field | Type | Notes |
+|---|---|---|
+| `eligibility` | `{ minimumAge: number; jurisdictionRestrictions?: string[] }` | Include when service has age or geographic restrictions. |
+| `accounts` | `{ registrationRequired: boolean; userResponsibleForCredentials: boolean; companyCanTerminate: boolean }` | Include when the service has user accounts. |
+| `prohibitedUses` | `string[]` | List of prohibited use descriptions. e.g. `["Scraping content without permission", "Impersonating other users"]`. |
+| `userContent` | `{ usersOwnContent: boolean; licenseGrantedToCompany: boolean; licenseDescription?: string; companyCanRemoveContent: boolean }` | Include when users upload or create content. |
+| `intellectualProperty` | `{ companyOwnsService: boolean; usersMayNotCopy: boolean }` | Standard IP clause. |
+| `payments` | `{ hasPaidFeatures: boolean; refundPolicy?: string; priceChangesNotice?: string }` | Include when service has paid tiers or subscriptions. |
+| `availability` | `{ noUptimeGuarantee: boolean; maintenanceWindows?: string }` | SaaS services typically include this. |
+| `termination` | `{ companyCanTerminate: boolean; userCanTerminate: boolean; effectOfTermination?: string }` | Include to describe account closure behavior. |
+| `disclaimers` | `{ serviceProvidedAsIs: boolean; noWarranties: boolean }` | Strongly recommended — validation emits a warning if absent. |
+| `limitationOfLiability` | `{ excludesIndirectDamages: boolean; liabilityCap?: string }` | Strongly recommended — validation emits a warning if absent. |
+| `indemnification` | `{ userIndemnifiesCompany: boolean; scope?: string }` | Include when the service exposes the company to user-generated liability. |
+| `thirdPartyServices` | `{ name: string; purpose: string }[]` | Third-party services embedded in the product (note: no `policyUrl` field here, unlike privacy's `thirdParties`). |
+| `disputeResolution` | `{ method: DisputeResolutionMethod; venue?: string; classActionWaiver?: boolean }` | Include to specify arbitration or litigation preference. |
+| `changesPolicy` | `{ noticeMethod: string; noticePeriodDays?: number }` | Describe how users are notified of ToS changes. |
+| `privacyPolicyUrl` | `string` | URL of the privacy policy. Cross-references the privacy document. |
+
+## DisputeResolutionMethod values
+
+| Value | Meaning |
+|---|---|
+| `"arbitration"` | Binding arbitration |
+| `"litigation"` | Court litigation |
+| `"mediation"` | Non-binding mediation |
+
+## Validation behavior
+
+- `effectiveDate` empty → fatal error
+- `company.*` fields empty → fatal error per field
+- `governingLaw.jurisdiction` empty or missing → fatal error
+- `acceptance.methods` empty → warning only
+- `disclaimers` absent → warning only
+- `limitationOfLiability` absent → warning only
+
+Source: `packages/core/src/validate-terms.ts`
+
+## Complete example
+
+```ts
+import { defineConfig } from "@openpolicy/sdk";
+
+export default defineConfig({
+  company: {
+    name: "Acme",
+    legalName: "Acme, Inc.",
+    address: "123 Main St, San Francisco, CA 94105",
+    contact: "legal@acme.com",
+  },
+  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,
+    },
+    prohibitedUses: [
+      "Scraping content without written permission",
+      "Using the service to distribute malware",
+      "Impersonating other users or Acme employees",
+    ],
+    userContent: {
+      usersOwnContent: true,
+      licenseGrantedToCompany: true,
+      licenseDescription: "A worldwide, royalty-free license to host and display your content.",
+      companyCanRemoveContent: true,
+    },
+    intellectualProperty: {
+      companyOwnsService: true,
+      usersMayNotCopy: true,
+    },
+    payments: {
+      hasPaidFeatures: true,
+      refundPolicy: "30-day money-back guarantee on annual plans.",
+      priceChangesNotice: "30 days written notice before price changes take effect.",
+    },
+    availability: {
+      noUptimeGuarantee: true,
+      maintenanceWindows: "Scheduled maintenance occurs Sundays 02:00–04:00 UTC.",
+    },
+    termination: {
+      companyCanTerminate: true,
+      userCanTerminate: true,
+      effectOfTermination: "All licenses granted to the user terminate immediately upon account closure.",
+    },
+    disclaimers: { serviceProvidedAsIs: true, noWarranties: true },
+    limitationOfLiability: {
+      excludesIndirectDamages: true,
+      liabilityCap: "fees paid by the user in the twelve months preceding the claim",
+    },
+    indemnification: {
+      userIndemnifiesCompany: true,
+      scope: "Claims arising from user content or user violations of these Terms.",
+    },
+    thirdPartyServices: [
+      { name: "Stripe", purpose: "Payment processing" },
+      { name: "AWS", purpose: "Cloud infrastructure" },
+    ],
+    disputeResolution: {
+      method: "arbitration",
+      venue: "San Francisco, CA",
+      classActionWaiver: true,
+    },
+    changesPolicy: {
+      noticeMethod: "Email notification to the address on your account",
+      noticePeriodDays: 30,
+    },
+    privacyPolicyUrl: "https://acme.com/privacy",
+  },
+});
+```