{"_id":"@54ruum/cookies","_rev":"2-809059464174545139de2aaa117ff840","name":"@54ruum/cookies","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@54ruum/cookies","version":"1.0.0","keywords":["54ruum","cookies","tracking"],"license":"MIT","_id":"@54ruum/cookies@1.0.0","maintainers":[{"name":"ayo-mi","email":"ajayijubrilayo@gmail.com"}],"homepage":"https://github.com/TheRuumAfrica/54ruum-cookies#readme","bugs":{"url":"https://github.com/TheRuumAfrica/54ruum-cookies/issues"},"dist":{"shasum":"0d000ac4073b41bee8a7290fd78ca3a1bd334416","tarball":"https://registry.npmjs.org/@54ruum/cookies/-/cookies-1.0.0.tgz","fileCount":6,"integrity":"sha512-I9mFvDwz/u8YWx/dAE9X633X4YyZ4j1d59C6HpxUMQInJmgAFvUHofN0JW2BgiyHLosk+jvRRW1qBOme0heFJw==","signatures":[{"sig":"MEQCIAxfyOVZ41FrRgCwtXaDUsEMy5wnWPvQtTM1VVM2ZMpbAiB9ux/cppRU+fB0DM9Kq3xgoW6D/Ogy08C0CU4gRGlC7g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":25956},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"58843371631e5b32070090e31d3a5773950c5475","scripts":{"dev":"tsup --watch","test":"vitest","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"ayo-mi","email":"ajayijubrilayo@gmail.com"},"repository":{"url":"git+https://github.com/TheRuumAfrica/54ruum-cookies.git","type":"git"},"_npmVersion":"10.9.3","description":"Cookie utilities for 54ruum.com subdomains","directories":{},"_nodeVersion":"22.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^2.0.0","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/cookies_1.0.0_1769312456799_0.47821385096909497","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@54ruum/cookies","version":"1.0.1","description":"Cookie utilities for 54ruum.com subdomains","main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsup","dev":"tsup --watch","prepublishOnly":"npm run build","test":"vitest"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.0.0","vitest":"^2.0.0"},"keywords":["54ruum","cookies","tracking"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/TheRuumAfrica/54ruum-cookies.git"},"publishConfig":{"access":"public"},"gitHead":"377287dbc6e854cea1898bfc9a95f363534bc389","_id":"@54ruum/cookies@1.0.1","bugs":{"url":"https://github.com/TheRuumAfrica/54ruum-cookies/issues"},"homepage":"https://github.com/TheRuumAfrica/54ruum-cookies#readme","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-1h3KMTDFauyvZcvWZInQ2euSpqbuZbiB1LeuAcOcUeXTsVmzTJy0xLBFxMz7bNDEfpgcKdE4U5cf/B7yuRqSzw==","shasum":"13a03e678f2e1a634b22a83ee5b7ff64f0b14355","tarball":"https://registry.npmjs.org/@54ruum/cookies/-/cookies-1.0.1.tgz","fileCount":6,"unpackedSize":26782,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDDweL3nlJeHTxl880YhrYNn6nCFWlcBKiRNhTu5oER2QIhAKv/mgeSw3szYg3pkWEUymZ5SQJkEGntGleT3p+n+aeJ"}]},"_npmUser":{"name":"ayo-mi","email":"ajayijubrilayo@gmail.com"},"directories":{},"maintainers":[{"name":"ayo-mi","email":"ajayijubrilayo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cookies_1.0.1_1784121399867_0.14565716463951484"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-25T03:40:56.595Z","modified":"2026-07-15T13:16:40.230Z","1.0.0":"2026-01-25T03:40:56.952Z","1.0.1":"2026-07-15T13:16:40.067Z"},"bugs":{"url":"https://github.com/TheRuumAfrica/54ruum-cookies/issues"},"license":"MIT","homepage":"https://github.com/TheRuumAfrica/54ruum-cookies#readme","keywords":["54ruum","cookies","tracking"],"repository":{"type":"git","url":"git+https://github.com/TheRuumAfrica/54ruum-cookies.git"},"description":"Cookie utilities for 54ruum.com subdomains","maintainers":[{"name":"ayo-mi","email":"ajayijubrilayo@gmail.com"}],"readme":"# @54ruum/cookies\n\nCookie utilities for 54ruum.com and its subdomains. This package provides cross-subdomain cookie management with a **hardcoded domain** for security.\n\n## Features\n\n- **Cross-subdomain cookies** - Works on `54ruum.com`, `app.54ruum.com`, `shop.54ruum.com`, etc.\n- **Hardcoded domain** - Cannot be misused on other domains\n- **Visitor tracking** - Persistent visitor IDs across subdomains\n- **Consent management** - GDPR-compliant consent preferences\n- **SSR support** - Works in both client and server environments\n- **TypeScript** - Full type definitions included\n\n## Installation\n\n```bash\nnpm install @54ruum/cookies\n# or\npnpm add @54ruum/cookies\n# or\nyarn add @54ruum/cookies\n```\n\n## Quick Start\n\n### Client-Side Usage\n\n```typescript\nimport { \n  setConsent, \n  getOrCreateVisitorId, \n  hasConsented \n} from \"@54ruum/cookies\";\n\n// Handle cookie consent popup\nfunction handleAcceptCookies() {\n  setConsent({ \n    analytics: true, \n    preferences: true, \n    marketing: false \n  });\n  \n  const visitorId = getOrCreateVisitorId();\n  console.log(\"Visitor ID:\", visitorId);\n}\n\n// Check if consent popup should be shown\nif (!hasConsented()) {\n  showConsentPopup();\n}\n```\n\n### Server-Side Usage (SSR)\n\n```typescript\nimport { parseCookies, getVisitorId, getConsentFromCookies } from \"@54ruum/cookies\";\n\n// React Router loader\nexport async function loader({ request }) {\n  const cookies = parseCookies(request.headers.get(\"Cookie\") || \"\");\n  const visitorId = getVisitorId(cookies);\n  const consent = getConsentFromCookies(cookies);\n  \n  return { \n    visitorId,\n    shouldLoadAnalytics: consent?.analytics ?? false \n  };\n}\n```\n\n## API Reference\n\n### Visitor Tracking\n\n#### `getOrCreateVisitorId(): string`\n\nGet existing visitor ID or create a new one (client-side only).\n\n```typescript\nconst visitorId = getOrCreateVisitorId();\n```\n\n#### `getVisitorId(cookies: ParsedCookies): string | null`\n\nGet visitor ID from parsed cookies (for server-side use).\n\n```typescript\nconst cookies = parseCookies(request.headers.get(\"Cookie\") || \"\");\nconst visitorId = getVisitorId(cookies);\n```\n\n#### `generateVisitorId(): string`\n\nGenerate a new UUID-style visitor ID.\n\n```typescript\nconst newId = generateVisitorId();\n```\n\n### Consent Management\n\n#### `setConsent(preferences: ConsentPreferences): void`\n\nStore user's cookie consent preferences.\n\n```typescript\nsetConsent({\n  analytics: true,\n  preferences: true,\n  marketing: false,\n});\n```\n\n#### `getConsent(): ConsentPreferences | null`\n\nGet current consent preferences (client-side).\n\n```typescript\nconst consent = getConsent();\nif (consent?.analytics) {\n  initAnalytics();\n}\n```\n\n#### `hasConsented(): boolean`\n\nCheck if user has given any consent.\n\n```typescript\nif (!hasConsented()) {\n  showConsentPopup();\n}\n```\n\n#### `getConsentFromCookies(cookies: ParsedCookies): ConsentPreferences | null`\n\nGet consent from parsed cookies (server-side).\n\n```typescript\nconst consent = getConsentFromCookies(parseCookies(cookieHeader));\n```\n\n### Core Cookie Operations\n\n#### `setCookie(name: string, value: string, options?: CookieOptions): void`\n\nSet a cookie (automatically uses `.54ruum.com` domain).\n\n```typescript\nsetCookie(\"my_cookie\", \"value\", { maxAge: 3600 });\n```\n\n#### `getCookie(name: string): string | null`\n\nGet a cookie value by name.\n\n```typescript\nconst value = getCookie(\"my_cookie\");\n```\n\n#### `deleteCookie(name: string): void`\n\nDelete a cookie.\n\n```typescript\ndeleteCookie(\"my_cookie\");\n```\n\n#### `parseCookies(cookieString: string): ParsedCookies`\n\nParse a cookie string into an object (for SSR).\n\n```typescript\nconst cookies = parseCookies(request.headers.get(\"Cookie\") || \"\");\n```\n\n### Constants\n\n```typescript\nimport { COOKIE_NAMES, COOKIE_MAX_AGE, COOKIE_DOMAIN } from \"@54ruum/cookies\";\n\nCOOKIE_DOMAIN      // \".54ruum.com\"\nCOOKIE_NAMES.VISITOR_ID   // \"ruum_vid\"\nCOOKIE_NAMES.CONSENT      // \"ruum_consent\"\nCOOKIE_NAMES.PREFERENCES  // \"ruum_prefs\"\nCOOKIE_NAMES.SESSION      // \"ruum_session\"\n\nCOOKIE_MAX_AGE.VISITOR     // 2 years (in seconds)\nCOOKIE_MAX_AGE.CONSENT     // 1 year\nCOOKIE_MAX_AGE.PREFERENCES // 1 year\nCOOKIE_MAX_AGE.SESSION     // 7 days\n```\n\n## Types\n\n```typescript\ninterface ConsentPreferences {\n  analytics: boolean;\n  preferences: boolean;\n  marketing: boolean;\n}\n\ninterface CookieOptions {\n  maxAge?: number;\n  path?: string;\n  secure?: boolean;\n  sameSite?: \"strict\" | \"lax\" | \"none\";\n  httpOnly?: boolean;\n}\n\ntype ParsedCookies = Record<string, string>;\n```\n\n## Security\n\nThis package is designed to work **exclusively** on `54ruum.com` and its subdomains. The domain is hardcoded and cannot be changed or overridden, preventing misuse on other domains.\n\n## Local Development\n\nThe package automatically detects localhost environments and skips the domain restriction, allowing cookies to work during local development:\n\n- `localhost`\n- `127.0.0.1`\n- `192.168.*` (local network)\n- `*.local` (mDNS)\n\nIn production on any `*.54ruum.com` domain, cookies are automatically shared across all subdomains.\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Watch mode\nnpm run dev\n\n# Run tests\nnpm test\n```\n\n## Local Development\n\nFor testing with other 54ruum projects before publishing:\n\n```bash\n# In this repo\nnpm link\n\n# In consumer repo\nnpm link @54ruum/cookies\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}