@openpolicy/sdk 0.0.19 → 0.0.20

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

package/skills/migrate/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: migrate
+description: >
+  Converting existing hand-written privacy policies or terms of service documents into OpenPolicy defineConfig() configs — mapping prose sections to structured TypeScript fields without passing raw text as values.
+type: lifecycle
+library: openpolicy
+library_version: "0.0.19"
+requires:
+  - openpolicy/define-config
+sources:
+  - jamiedavenport/openpolicy:packages/core/src/types.ts
+  - jamiedavenport/openpolicy:packages/sdk/src/constants.ts
+---
+
+# openpolicy/migrate
+
+This skill builds on openpolicy/define-config. Read it first.
+
+OpenPolicy generates all prose from structured fields. The job of a migration is to extract structure from an existing document — not to transcribe its sentences. Every field value must be a short label, boolean, enum string, or object; never a paragraph.
+
+## Setup: Before and After
+
+### Existing privacy policy (excerpt)
+
+```
+Privacy Policy — Effective January 1, 2026
+
+Acme, Inc. ("Acme") operates the Acme platform. This policy describes how we collect
+and use personal data in compliance with the GDPR and the California Consumer Privacy Act.
+
+Data We Collect
+We collect the following categories of personal data:
+- Account information: your name, email address, and password when you register.
+- Payment details: the last 4 digits of your card, your billing name, and billing address.
+- Usage data: pages you visit, features you use, and time spent in the app.
+- Device information: your device type, operating system, and browser version.
+
+We use Google Analytics for product analytics and Stripe for payment processing.
+
+Legal Basis (GDPR)
+We process your data on the basis of legitimate interests and, where required, consent.
+
+Data Retention
+Account information is held until you delete your account. Usage data is retained for
+90 days. Payment records are kept for 3 years as required by applicable law.
+
+Your Rights
+Under the GDPR you have the right to access, correct, erase, port, restrict, and object
+to processing of your data. California residents may opt out of the sale of personal
+information and are protected from discrimination for exercising their rights.
+
+Contact: privacy@acme.com | Acme, Inc., 123 Main St, San Francisco, CA 94105
+```
+
+### Migrated config
+
+```ts
+// openpolicy.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",
+    // GDPR + CCPA: spread both presets, then union the array fields
+    ...Compliance.GDPR,
+    jurisdictions: [
+      ...Compliance.GDPR.jurisdictions,
+      ...Compliance.CCPA.jurisdictions,
+    ],
+    userRights: [
+      ...Compliance.GDPR.userRights,
+      ...Compliance.CCPA.userRights,
+    ],
+    dataCollected: {
+      ...dataCollected,
+      ...DataCategories.AccountInfo,
+      ...DataCategories.PaymentInfo,
+      ...DataCategories.UsageData,
+      ...DataCategories.DeviceInfo,
+    },
+    retention: {
+      "Account Information": Retention.UntilAccountDeletion,
+      "Usage Data": Retention.NinetyDays,
+      "Payment Information": Retention.ThreeYears,
+    },
+    cookies: { essential: true, analytics: true, marketing: false },
+    thirdParties: [
+      ...thirdParties,
+      Providers.GoogleAnalytics,
+      Providers.Stripe,
+    ],
+  },
+});
+```
+
+## Core Patterns
+
+### 1. Mapping data collection sections
+
+Read each "data we collect" section and identify the category name and the specific fields listed. Map each to a short label — never copy sentences.
+
+`DataCategories` presets cover the most common categories. Check if the existing policy's categories match before reaching for custom keys:
+
+| Preset | Generated key | Fields |
+|---|---|---|
+| `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 |
+
+For categories not covered by a preset, add a custom key with short field labels:
+
+```ts
+dataCollected: {
+  ...dataCollected,
+  ...DataCategories.AccountInfo,
+  "Health Data": ["Blood glucose readings", "Heart rate"],
+},
+```
+
+Always spread `dataCollected` first so the autoCollect plugin's output is included alongside the explicit entries.
+
+### 2. Mapping jurisdiction and legal basis from GDPR/CCPA language
+
+Scan the existing policy for jurisdiction signals:
+
+| Prose signal | Maps to |
+|---|---|
+| "GDPR", "EU", "EEA", "European" | `jurisdictions: ["eu"]` |
+| "CCPA", "California", "California residents" | `jurisdictions: ["ca"]` |
+| "Australian Privacy Act" | `jurisdictions: ["au"]` |
+| No specific regulation cited | `jurisdictions: ["us"]` |
+
+For legal basis (GDPR policies only), map the stated basis:
+
+| Prose | `legalBasis` value |
+|---|---|
+| "legitimate interests" | `"legitimate_interests"` |
+| "your consent" / "you have agreed" | `"consent"` |
+| "to perform a contract" / "to provide the service" | `"contract"` |
+| "legal obligation" / "required by law" | `"legal_obligation"` |
+
+When the policy states more than one basis, use an array:
+
+```ts
+legalBasis: ["legitimate_interests", "consent"],
+```
+
+Use `Compliance.GDPR` or `Compliance.CCPA` as a starting point when the existing policy explicitly targets those regulations. Merge the array fields when both apply:
+
+```ts
+...Compliance.GDPR,
+jurisdictions: [...Compliance.GDPR.jurisdictions, ...Compliance.CCPA.jurisdictions],
+userRights: [...Compliance.GDPR.userRights, ...Compliance.CCPA.userRights],
+```
+
+`Compliance.CCPA` does not include `legalBasis` — only add it when the existing policy states an EU legal basis.
+
+### 3. Mapping TermsOfService optional sections
+
+`TermsOfServiceConfig` has three required fields (`effectiveDate`, `acceptance`, `governingLaw`) and many optional ones. The rule for migration: if the existing document has a section covering a concept, include the corresponding config field.
+
+Read each section heading and match it:
+
+| Existing section | Config field |
+|---|---|
+| Age / eligibility requirements | `eligibility` |
+| Account creation, credentials | `accounts` |
+| Prohibited conduct / acceptable use | `prohibitedUses` |
+| User-generated content, uploads | `userContent` |
+| Intellectual property, trademarks | `intellectualProperty` |
+| Pricing, subscriptions, refunds | `payments` |
+| Uptime, maintenance | `availability` |
+| Account suspension / cancellation | `termination` |
+| Disclaimer of warranties | `disclaimers` |
+| Limitation of liability | `limitationOfLiability` |
+| Indemnification | `indemnification` |
+| Third-party services / links | `thirdPartyServices` |
+| Dispute resolution, arbitration | `disputeResolution` |
+| How changes are communicated | `changesPolicy` |
+| Link to privacy policy | `privacyPolicyUrl` |
+
+A full migration for a SaaS product with payments, user content, and arbitration:
+
+```ts
+terms: {
+  effectiveDate: "2026-01-01",
+  acceptance: { methods: ["creating an account", "using the service"] },
+  governingLaw: { jurisdiction: "Delaware, USA" },
+  eligibility: { minimumAge: 18 },
+  accounts: {
+    registrationRequired: true,
+    userResponsibleForCredentials: true,
+    companyCanTerminate: true,
+  },
+  prohibitedUses: [
+    "Reverse engineering the service",
+    "Automated scraping without prior written consent",
+    "Using the service to violate applicable law",
+  ],
+  userContent: {
+    usersOwnContent: true,
+    licenseGrantedToCompany: true,
+    licenseDescription: "A worldwide, royalty-free license to host and display your content.",
+    companyCanRemoveContent: true,
+  },
+  payments: {
+    hasPaidFeatures: true,
+    refundPolicy: "30-day money-back guarantee on annual plans.",
+    priceChangesNotice: "30 days advance notice via email.",
+  },
+  termination: {
+    companyCanTerminate: true,
+    userCanTerminate: true,
+    effectOfTermination: "All licenses granted to the user terminate immediately.",
+  },
+  disclaimers: { serviceProvidedAsIs: true, noWarranties: true },
+  limitationOfLiability: {
+    excludesIndirectDamages: true,
+    liabilityCap: "Fees paid in the prior 12 months.",
+  },
+  disputeResolution: {
+    method: "arbitration",
+    venue: "San Francisco, CA",
+    classActionWaiver: true,
+  },
+  changesPolicy: {
+    noticeMethod: "Email notification",
+    noticePeriodDays: 30,
+  },
+  privacyPolicyUrl: "https://acme.com/privacy",
+},
+```
+
+### 4. Using presets to standardize values
+
+Prefer preset constants over raw strings wherever the meaning matches exactly. This reduces typo risk and keeps the config readable.
+
+**Retention periods** — match common prose to preset keys:
+
+| Prose | Preset |
+|---|---|
+| "until you delete your account" | `Retention.UntilAccountDeletion` |
+| "until your session ends" | `Retention.UntilSessionExpiry` |
+| "30 days" | `Retention.ThirtyDays` |
+| "90 days" | `Retention.NinetyDays` |
+| "1 year" | `Retention.OneYear` |
+| "3 years" | `Retention.ThreeYears` |
+| "as required by law" | `Retention.AsRequiredByLaw` |
+
+For a period not in the preset list, use a plain string:
+
+```ts
+retention: {
+  "Audit Logs": "7 years",
+},
+```
+
+**User rights** — `UserRight` enum values and their prose equivalents:
+
+| Prose | Value |
+|---|---|
+| right of access / to view your data | `"access"` |
+| right to correct / rectify | `"rectification"` |
+| right to delete / erasure / "right to be forgotten" | `"erasure"` |
+| right to data portability | `"portability"` |
+| right to restrict processing | `"restriction"` |
+| right to object | `"objection"` |
+| right to opt out of sale | `"opt_out_sale"` |
+| right to non-discrimination | `"non_discrimination"` |
+
+## Common Mistakes
+
+### HIGH — Passing prose text as field values instead of mapping to structured fields
+
+OpenPolicy generates all human-readable sentences from the config structure. Passing paragraph text into fields produces malformed or legally duplicated output.
+
+Wrong:
+```ts
+privacy: {
+  dataCollected: {
+    // WRONG: prose sentence passed as a field label
+    "Data": ["We collect information you provide when you register for an account, including your name and email address."],
+  },
+}
+```
+
+Correct:
+```ts
+privacy: {
+  dataCollected: {
+    "Account Information": ["Name", "Email address"],
+  },
+}
+```
+
+The same principle applies to `prohibitedUses` (keep each entry to a short clause, not a full paragraph), `acceptance.methods` (short action phrases, not sentences), and `payments.refundPolicy` (one concise sentence is acceptable; not a multi-paragraph refund terms block).
+
+Source: `packages/core/src/types.ts`
+
+---
+
+### MEDIUM — Omitting optional TermsOfService sections that cover existing policy content
+
+Skipping optional sections when the existing document has matching content produces a terms document that is legally less complete than what the team approved.
+
+Wrong:
+```ts
+// Existing policy has payment terms, user content policy, and account termination section —
+// but all three are omitted from the config.
+terms: {
+  effectiveDate: "2026-01-01",
+  acceptance: { methods: ["using the service"] },
+  governingLaw: { jurisdiction: "Delaware, USA" },
+}
+```
+
+Correct:
+```ts
+terms: {
+  effectiveDate: "2026-01-01",
+  acceptance: { methods: ["using the service"] },
+  governingLaw: { jurisdiction: "Delaware, USA" },
+  payments: {
+    hasPaidFeatures: true,
+    refundPolicy: "30-day money-back guarantee.",
+    priceChangesNotice: "30 days advance notice.",
+  },
+  userContent: {
+    usersOwnContent: true,
+    licenseGrantedToCompany: true,
+    companyCanRemoveContent: true,
+  },
+  termination: {
+    companyCanTerminate: true,
+    userCanTerminate: true,
+  },
+}
+```
+
+Before finalizing the config, re-read each section of the original document and confirm a corresponding field is present in the output config. Optional sections that are absent from the config are entirely omitted from the compiled document — there is no fallback prose.
+
+Source: `packages/core/src/types.ts`