@openpolicy/sdk 0.0.18 → 0.0.20

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",
+  },
+});
+```

package/skills/getting-started/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: getting-started
+description: >
+  End-to-end setup for OpenPolicy: install @openpolicy/sdk, @openpolicy/react, and
+  @openpolicy/vite-auto-collect; create openpolicy.ts with defineConfig(); wire autoCollect()
+  into vite.config.ts; wrap the React app with <OpenPolicy>; render <PrivacyPolicy>.
+type: lifecycle
+library: openpolicy
+library_version: "0.0.19"
+sources:
+  - jamiedavenport/openpolicy:packages/sdk/README.md
+  - jamiedavenport/openpolicy:packages/react/src/context.tsx
+  - jamiedavenport/openpolicy:packages/vite-auto-collect/src/index.ts
+---
+
+## Setup
+
+Install packages:
+
+```sh
+bun add @openpolicy/sdk @openpolicy/react @openpolicy/vite-auto-collect
+```
+
+Create `openpolicy.ts` at the project root:
+
+```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,
+      "Account Information": ["Email address", "Display name"],
+    },
+    thirdParties: [...thirdParties],
+  },
+});
+```
+
+Add `autoCollect()` to `vite.config.ts` — it must appear before any React plugin:
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { autoCollect } from "@openpolicy/vite-auto-collect";
+
+export default defineConfig({
+  plugins: [
+    autoCollect({ thirdParties: { usePackageJson: true } }),
+    react(),
+  ],
+});
+```
+
+Wrap the application root with `<OpenPolicy>`:
+
+```tsx
+// main.tsx or _app.tsx or layout.tsx
+import { OpenPolicy } from "@openpolicy/react";
+import config from "./openpolicy";
+
+export function App({ children }: { children: React.ReactNode }) {
+  return <OpenPolicy config={config}>{children}</OpenPolicy>;
+}
+```
+
+Render a policy page:
+
+```tsx
+import { PrivacyPolicy } from "@openpolicy/react";
+import "@openpolicy/react/styles.css";
+
+export default function PrivacyPage() {
+  return <PrivacyPolicy />;
+}
+```
+
+## Core Patterns
+
+### Mark data collection inline with `collecting()`
+
+```ts
+import { collecting } from "@openpolicy/sdk";
+
+// Call next to the point of collection; autoCollect() scans for these at build time
+export async function createUser(name: string, email: string) {
+  const user = collecting(
+    "Account Information",
+    { name, email },
+    { name: "Display name", email: "Email address" },
+  );
+  return db.users.create(user);
+}
+```
+
+The category and label arguments must be string literals — dynamic variables are silently skipped by the static scanner.
+
+### Mark third-party integrations with `thirdParty()`
+
+```ts
+import { thirdParty } from "@openpolicy/sdk";
+
+// Place next to the integration's initialisation
+thirdParty("Stripe", "Payment processing", "https://stripe.com/privacy");
+```
+
+The `autoCollect({ thirdParties: { usePackageJson: true } })` option also auto-detects ~30 known packages (Stripe, Sentry, PostHog, etc.) from `package.json`.
+
+### Spread both sentinels in `openpolicy.ts`
+
+```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,                          // populated by autoCollect() at build time
+      "Manual Category": ["Manually added field"], // additional hand-declared entries
+    },
+    thirdParties: [...thirdParties],             // populated by autoCollect() at build time
+  },
+});
+```
+
+Both `dataCollected` and `thirdParties` are placeholder objects in `@openpolicy/sdk`; `autoCollect()` replaces them via virtual module injection during the Vite build.
+
+## Common Mistakes
+
+### CRITICAL: Using `openPolicy()` from `@openpolicy/vite` instead of `autoCollect()`
+
+Wrong:
+```ts
+// vite.config.ts
+import { openPolicy } from "@openpolicy/vite";
+
+export default defineConfig({
+  plugins: [openPolicy({ formats: ["markdown"], outDir: "public/policies" })],
+});
+```
+
+Correct:
+```ts
+// vite.config.ts
+import { autoCollect } from "@openpolicy/vite-auto-collect";
+
+export default defineConfig({
+  plugins: [autoCollect()],
+});
+```
+
+`openPolicy()` generates static files at build time that React components never read; `autoCollect()` populates the `dataCollected` and `thirdParties` sentinels that feed the React runtime rendering path.
+
+Source: maintainer interview
+
+---
+
+### HIGH: Rendering policy components without `<OpenPolicy>` provider
+
+Wrong:
+```tsx
+// privacy-page.tsx
+import { PrivacyPolicy } from "@openpolicy/react";
+
+export default function PrivacyPage() {
+  return <PrivacyPolicy />;
+}
+```
+
+Correct:
+```tsx
+// layout.tsx — wrap at the root
+import { OpenPolicy } from "@openpolicy/react";
+import config from "./openpolicy";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <OpenPolicy config={config}>{children}</OpenPolicy>;
+}
+
+// privacy-page.tsx — component reads from context
+import { PrivacyPolicy } from "@openpolicy/react";
+
+export default function PrivacyPage() {
+  return <PrivacyPolicy />;
+}
+```
+
+`PrivacyPolicy`, `TermsOfService`, and `CookiePolicy` read config from React context; without the provider they silently render `null` with no visible error.
+
+Source: packages/react/src/context.tsx
+
+---
+
+### HIGH: Not spreading `dataCollected` and `thirdParties` sentinels into config
+
+Wrong:
+```ts
+// openpolicy.ts
+import { defineConfig } 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: { "Account Information": ["Email address"] },
+    thirdParties: [],
+  },
+});
+```
+
+Correct:
+```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, "Account Information": ["Email address"] },
+    thirdParties: [...thirdParties],
+  },
+});
+```
+
+Without spreading the sentinels, `autoCollect()` plugin output is discarded and the policy compiles with only the hand-declared entries — all `collecting()` and `thirdParty()` call annotations are silently ignored.
+
+Source: packages/sdk/src/auto-collected.ts