@rep-protocol/sdk 0.1.2

package/LICENSE

@@ -0,0 +1,9 @@
+Specification documents (spec/, schema/) are licensed under:
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+https://creativecommons.org/licenses/by/4.0/
+
+Reference implementations and tooling are licensed under:
+Apache License, Version 2.0
+https://www.apache.org/licenses/LICENSE-2.0
+
+Copyright 2026 Ruach Tech

package/README.md

@@ -0,0 +1,76 @@
+# @rep-protocol/sdk
+
+Client SDK for the [Runtime Environment Protocol](https://github.com/ruachtech/rep).
+
+Zero-dependency, framework-agnostic, ~1.5KB gzipped. Reads environment variables injected by the REP gateway at runtime — no build tool plugins, no framework coupling.
+
+## Install
+
+```bash
+npm install @rep-protocol/sdk
+```
+
+## Usage
+
+```typescript
+import { rep } from '@rep-protocol/sdk';
+
+// PUBLIC tier — synchronous, immediate, no network call.
+const apiUrl = rep.get('API_URL');
+const flags = rep.get('FEATURE_FLAGS', '').split(',');
+
+// SENSITIVE tier — async, fetches session key, decrypts.
+const analyticsKey = await rep.getSecure('ANALYTICS_KEY');
+
+// All public vars as a frozen object.
+const all = rep.getAll();
+
+// Verify payload integrity.
+if (!rep.verify()) {
+  console.error('Config may have been tampered with!');
+}
+
+// Hot reload (if gateway has --hot-reload enabled).
+const unsub = rep.onChange('FEATURE_FLAGS', (newVal, oldVal) => {
+  console.log(`Flags changed: ${oldVal} → ${newVal}`);
+});
+
+// Cleanup.
+unsub();
+```
+
+## API
+
+| Method | Returns | Description |
+|---|---|---|
+| `rep.get(key, default?)` | `string \| undefined` | Synchronous. PUBLIC tier variable. |
+| `rep.getSecure(key)` | `Promise<string>` | Async. SENSITIVE tier variable (decrypts via session key). |
+| `rep.getAll()` | `Record<string, string>` | All PUBLIC vars as a frozen object. |
+| `rep.verify()` | `boolean` | Check payload integrity. |
+| `rep.meta()` | `REPMeta \| null` | Payload metadata (version, counts, status). |
+| `rep.onChange(key, cb)` | `() => void` | Subscribe to hot reload changes. Returns unsubscribe fn. |
+| `rep.onAnyChange(cb)` | `() => void` | Subscribe to all changes. Returns unsubscribe fn. |
+
+## Development Mode
+
+Without the REP gateway, `rep.get()` returns `undefined`. Use defaults:
+
+```typescript
+const apiUrl = rep.get('API_URL', 'http://localhost:3000');
+```
+
+Or mock the payload in your `index.html` during development:
+
+```html
+<script id="__rep__" type="application/json">
+{"public":{"API_URL":"http://localhost:3000"},"_meta":{"version":"0.1.0","injected_at":"2026-01-01T00:00:00Z","integrity":"hmac-sha256:dev","ttl":0}}
+</script>
+```
+
+## Specification
+
+Implements [REP-RFC-0001 §5 — Client SDK Specification](https://github.com/ruachtech/rep/blob/main/spec/REP-RFC-0001.md#5-client-sdk-specification).
+
+## License
+
+Apache 2.0

package/dist/index.d.mts

@@ -0,0 +1,84 @@
+/**
+ * @rep-protocol/sdk — Client SDK for the Runtime Environment Protocol.
+ *
+ * Zero-dependency, framework-agnostic SDK for reading environment variables
+ * injected by the REP gateway.
+ *
+ * PUBLIC tier variables are available synchronously via `rep.get()`.
+ * SENSITIVE tier variables require async decryption via `rep.getSecure()`.
+ *
+ * @see https://github.com/ruachtech/rep — REP-RFC-0001 §5
+ * @license Apache-2.0
+ * @version 0.1.0
+ */
+interface REPMeta {
+    version: string;
+    injectedAt: Date;
+    integrityValid: boolean;
+    publicCount: number;
+    sensitiveAvailable: boolean;
+    hotReloadAvailable: boolean;
+}
+type ChangeCallback = (newValue: string, oldValue: string | undefined) => void;
+type AnyChangeCallback = (key: string, newValue: string, oldValue: string | undefined) => void;
+/**
+ * Retrieve a PUBLIC tier variable. Synchronous — no network call.
+ *
+ * Per §5.2: when called with a defaultValue the return type narrows to string.
+ *
+ * @param key - Variable name (without REP_PUBLIC_ prefix).
+ * @param defaultValue - Fallback if the variable is not present.
+ */
+declare function get(key: string, defaultValue: string): string;
+declare function get(key: string, defaultValue?: undefined): string | undefined;
+/**
+ * Retrieve a SENSITIVE tier variable. Async — fetches a session key.
+ *
+ * Per §5.2, decrypted values are cached in memory for the page lifetime.
+ *
+ * @param key - Variable name (without REP_SENSITIVE_ prefix).
+ * @throws REPError if the session key endpoint is unreachable or decryption fails.
+ */
+declare function getSecure(key: string): Promise<string>;
+/**
+ * Retrieve all PUBLIC tier variables as a frozen object. Synchronous.
+ */
+declare function getAll(): Readonly<Record<string, string>>;
+/**
+ * Verify payload integrity. Synchronous check of the tamper flag.
+ * For full async SRI verification, use meta().integrityValid.
+ */
+declare function verify(): boolean;
+/**
+ * Returns metadata about the current REP payload.
+ * Returns null if no payload is present.
+ */
+declare function meta(): REPMeta | null;
+/**
+ * Register a callback for when a specific PUBLIC variable changes.
+ *
+ * If hot reload is not available, logs a warning and returns a no-op unsubscribe.
+ * Per §5.3 step 7: SSE connection is established lazily on first onChange call.
+ */
+declare function onChange(key: string, callback: ChangeCallback): () => void;
+/**
+ * Register a callback for any variable change.
+ */
+declare function onAnyChange(callback: AnyChangeCallback): () => void;
+/**
+ * The `rep` namespace object for convenient named import:
+ *
+ *   import { rep } from '@rep-protocol/sdk';
+ *   const url = rep.get('API_URL');
+ */
+declare const rep: {
+    get: typeof get;
+    getSecure: typeof getSecure;
+    getAll: typeof getAll;
+    verify: typeof verify;
+    meta: typeof meta;
+    onChange: typeof onChange;
+    onAnyChange: typeof onAnyChange;
+};
+
+export { rep as default, get, getAll, getSecure, meta, onAnyChange, onChange, rep, verify };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @rep-protocol/sdk — Client SDK for the Runtime Environment Protocol.
+ *
+ * Zero-dependency, framework-agnostic SDK for reading environment variables
+ * injected by the REP gateway.
+ *
+ * PUBLIC tier variables are available synchronously via `rep.get()`.
+ * SENSITIVE tier variables require async decryption via `rep.getSecure()`.
+ *
+ * @see https://github.com/ruachtech/rep — REP-RFC-0001 §5
+ * @license Apache-2.0
+ * @version 0.1.0
+ */
+interface REPMeta {
+    version: string;
+    injectedAt: Date;
+    integrityValid: boolean;
+    publicCount: number;
+    sensitiveAvailable: boolean;
+    hotReloadAvailable: boolean;
+}
+type ChangeCallback = (newValue: string, oldValue: string | undefined) => void;
+type AnyChangeCallback = (key: string, newValue: string, oldValue: string | undefined) => void;
+/**
+ * Retrieve a PUBLIC tier variable. Synchronous — no network call.
+ *
+ * Per §5.2: when called with a defaultValue the return type narrows to string.
+ *
+ * @param key - Variable name (without REP_PUBLIC_ prefix).
+ * @param defaultValue - Fallback if the variable is not present.
+ */
+declare function get(key: string, defaultValue: string): string;
+declare function get(key: string, defaultValue?: undefined): string | undefined;
+/**
+ * Retrieve a SENSITIVE tier variable. Async — fetches a session key.
+ *
+ * Per §5.2, decrypted values are cached in memory for the page lifetime.
+ *
+ * @param key - Variable name (without REP_SENSITIVE_ prefix).
+ * @throws REPError if the session key endpoint is unreachable or decryption fails.
+ */
+declare function getSecure(key: string): Promise<string>;
+/**
+ * Retrieve all PUBLIC tier variables as a frozen object. Synchronous.
+ */
+declare function getAll(): Readonly<Record<string, string>>;
+/**
+ * Verify payload integrity. Synchronous check of the tamper flag.
+ * For full async SRI verification, use meta().integrityValid.
+ */
+declare function verify(): boolean;
+/**
+ * Returns metadata about the current REP payload.
+ * Returns null if no payload is present.
+ */
+declare function meta(): REPMeta | null;
+/**
+ * Register a callback for when a specific PUBLIC variable changes.
+ *
+ * If hot reload is not available, logs a warning and returns a no-op unsubscribe.
+ * Per §5.3 step 7: SSE connection is established lazily on first onChange call.
+ */
+declare function onChange(key: string, callback: ChangeCallback): () => void;
+/**
+ * Register a callback for any variable change.
+ */
+declare function onAnyChange(callback: AnyChangeCallback): () => void;
+/**
+ * The `rep` namespace object for convenient named import:
+ *
+ *   import { rep } from '@rep-protocol/sdk';
+ *   const url = rep.get('API_URL');
+ */
+declare const rep: {
+    get: typeof get;
+    getSecure: typeof getSecure;
+    getAll: typeof getAll;
+    verify: typeof verify;
+    meta: typeof meta;
+    onChange: typeof onChange;
+    onAnyChange: typeof onAnyChange;
+};
+
+export { rep as default, get, getAll, getSecure, meta, onAnyChange, onChange, rep, verify };

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";var b=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var I=Object.getOwnPropertyNames;var z=Object.prototype.hasOwnProperty;var N=(e,t)=>{for(var n in t)b(e,n,{get:t[n],enumerable:!0})},K=(e,t,n,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of I(t))!z.call(e,o)&&o!==n&&b(e,o,{get:()=>t[o],enumerable:!(a=O(t,o))||a.enumerable});return e};var T=e=>K(b({},"__esModule",{value:!0}),e);var H={};N(H,{default:()=>D,get:()=>E,getAll:()=>w,getSecure:()=>m,meta:()=>S,onAnyChange:()=>x,onChange:()=>R,rep:()=>V,verify:()=>C});module.exports=T(H);var g=class extends Error{constructor(t){super(`[REP] ${t}`),this.name="REPError"}},r=null,i=!1,v=!1,l=Object.freeze({}),p=null,d=null,c=new Map,f=new Set;function B(){if(typeof document>"u"){i=!1;return}let e=document.getElementById("__rep__");if(!e){i=!1;return}try{r=JSON.parse(e.textContent||"")}catch(n){console.error("[REP] Failed to parse payload:",n),i=!1;return}if(!r||!r.public||!r._meta){console.error("[REP] Payload is malformed \u2014 missing required fields."),i=!1;return}let t=e.getAttribute("data-rep-integrity");t&&$(e.textContent||"",t).then(n=>{n||(console.error("[REP] Integrity check failed \u2014 payload may have been tampered with."),v=!0)}),l=Object.freeze({...r.public}),i=!0}async function $(e,t){if(!t.startsWith("sha256-"))return!1;let n=t.slice(7);try{let o=new TextEncoder().encode(e),s=await crypto.subtle.digest("SHA-256",o),u=new Uint8Array(s);return btoa(String.fromCharCode(...u))===n}catch{return!1}}B();function E(e,t){if(!i)return t;let n=l[e];return n!==void 0?n:t}async function m(e){if(!i||!r)throw new g("REP payload not available.");if(!r.sensitive||!r._meta.key_endpoint)throw new g("No SENSITIVE tier variables in payload.");if(p&&e in p)return p[e];let t=await fetch(r._meta.key_endpoint);if(!t.ok)throw new g(`Session key request failed: ${t.status} ${t.statusText}`);let n=await t.json(),a=Uint8Array.from(atob(n.key),h=>h.charCodeAt(0)),o=Uint8Array.from(atob(r.sensitive),h=>h.charCodeAt(0)),s=o.slice(0,12),u=o.slice(12),_=await crypto.subtle.importKey("raw",a,{name:"AES-GCM"},!1,["decrypt"]),j=new TextEncoder().encode(r._meta.integrity),k=await crypto.subtle.decrypt({name:"AES-GCM",iv:s,additionalData:j},_,u),M=new TextDecoder,y=JSON.parse(M.decode(k));if(p=y,!(e in y))throw new g(`SENSITIVE variable "${e}" not found in payload.`);return y[e]}function w(){return l}function C(){return i&&!v}function S(){return!i||!r?null:{version:r._meta.version,injectedAt:new Date(r._meta.injected_at),integrityValid:!v,publicCount:Object.keys(r.public).length,sensitiveAvailable:!!r.sensitive,hotReloadAvailable:!!r._meta.hot_reload}}function R(e,t){return!i||!r?._meta.hot_reload?(console.warn(`[REP] Hot reload not available. onChange("${e}") is a no-op.`),()=>{}):(A(),c.has(e)||c.set(e,new Set),c.get(e).add(t),()=>{c.get(e)?.delete(t),c.get(e)?.size===0&&c.delete(e),P()})}function x(e){return!i||!r?._meta.hot_reload?(console.warn("[REP] Hot reload not available. onAnyChange() is a no-op."),()=>{}):(A(),f.add(e),()=>{f.delete(e),P()})}function A(){d||!r?._meta.hot_reload||(d=new EventSource(r._meta.hot_reload),d.addEventListener("rep:config:update",e=>{try{let t=JSON.parse(e.data),{key:n,value:a}=t,o=l[n],s={...l,[n]:a};l=Object.freeze(s),r&&(r.public[n]=a),c.get(n)?.forEach(u=>u(a,o)),f.forEach(u=>u(n,a,o))}catch(t){console.error("[REP] Failed to process hot reload event:",t)}}),d.addEventListener("rep:config:delete",e=>{try{let t=JSON.parse(e.data),{key:n}=t,a=l[n],o={...l};delete o[n],l=Object.freeze(o),r&&delete r.public[n],c.get(n)?.forEach(s=>s("",a)),f.forEach(s=>s(n,"",a))}catch(t){console.error("[REP] Failed to process hot reload delete:",t)}}),d.onerror=()=>{console.warn("[REP] Hot reload SSE connection lost. Will reconnect automatically.")})}function P(){c.size===0&&f.size===0&&d&&(d.close(),d=null)}var V={get:E,getSecure:m,getAll:w,verify:C,meta:S,onChange:R,onAnyChange:x},D=V;0&&(module.exports={get,getAll,getSecure,meta,onAnyChange,onChange,rep,verify});
+/**
+ * @rep-protocol/sdk — Client SDK for the Runtime Environment Protocol.
+ *
+ * Zero-dependency, framework-agnostic SDK for reading environment variables
+ * injected by the REP gateway.
+ *
+ * PUBLIC tier variables are available synchronously via `rep.get()`.
+ * SENSITIVE tier variables require async decryption via `rep.getSecure()`.
+ *
+ * @see https://github.com/ruachtech/rep — REP-RFC-0001 §5
+ * @license Apache-2.0
+ * @version 0.1.0
+ */

package/dist/index.mjs

@@ -0,0 +1,14 @@
+var g=class extends Error{constructor(t){super(`[REP] ${t}`),this.name="REPError"}},n=null,o=!1,b=!1,l=Object.freeze({}),p=null,d=null,c=new Map,f=new Set;function S(){if(typeof document>"u"){o=!1;return}let e=document.getElementById("__rep__");if(!e){o=!1;return}try{n=JSON.parse(e.textContent||"")}catch(r){console.error("[REP] Failed to parse payload:",r),o=!1;return}if(!n||!n.public||!n._meta){console.error("[REP] Payload is malformed \u2014 missing required fields."),o=!1;return}let t=e.getAttribute("data-rep-integrity");t&&R(e.textContent||"",t).then(r=>{r||(console.error("[REP] Integrity check failed \u2014 payload may have been tampered with."),b=!0)}),l=Object.freeze({...n.public}),o=!0}async function R(e,t){if(!t.startsWith("sha256-"))return!1;let r=t.slice(7);try{let i=new TextEncoder().encode(e),s=await crypto.subtle.digest("SHA-256",i),u=new Uint8Array(s);return btoa(String.fromCharCode(...u))===r}catch{return!1}}S();function x(e,t){if(!o)return t;let r=l[e];return r!==void 0?r:t}async function A(e){if(!o||!n)throw new g("REP payload not available.");if(!n.sensitive||!n._meta.key_endpoint)throw new g("No SENSITIVE tier variables in payload.");if(p&&e in p)return p[e];let t=await fetch(n._meta.key_endpoint);if(!t.ok)throw new g(`Session key request failed: ${t.status} ${t.statusText}`);let r=await t.json(),a=Uint8Array.from(atob(r.key),h=>h.charCodeAt(0)),i=Uint8Array.from(atob(n.sensitive),h=>h.charCodeAt(0)),s=i.slice(0,12),u=i.slice(12),v=await crypto.subtle.importKey("raw",a,{name:"AES-GCM"},!1,["decrypt"]),m=new TextEncoder().encode(n._meta.integrity),w=await crypto.subtle.decrypt({name:"AES-GCM",iv:s,additionalData:m},v,u),C=new TextDecoder,y=JSON.parse(C.decode(w));if(p=y,!(e in y))throw new g(`SENSITIVE variable "${e}" not found in payload.`);return y[e]}function P(){return l}function V(){return o&&!b}function j(){return!o||!n?null:{version:n._meta.version,injectedAt:new Date(n._meta.injected_at),integrityValid:!b,publicCount:Object.keys(n.public).length,sensitiveAvailable:!!n.sensitive,hotReloadAvailable:!!n._meta.hot_reload}}function k(e,t){return!o||!n?._meta.hot_reload?(console.warn(`[REP] Hot reload not available. onChange("${e}") is a no-op.`),()=>{}):(_(),c.has(e)||c.set(e,new Set),c.get(e).add(t),()=>{c.get(e)?.delete(t),c.get(e)?.size===0&&c.delete(e),E()})}function M(e){return!o||!n?._meta.hot_reload?(console.warn("[REP] Hot reload not available. onAnyChange() is a no-op."),()=>{}):(_(),f.add(e),()=>{f.delete(e),E()})}function _(){d||!n?._meta.hot_reload||(d=new EventSource(n._meta.hot_reload),d.addEventListener("rep:config:update",e=>{try{let t=JSON.parse(e.data),{key:r,value:a}=t,i=l[r],s={...l,[r]:a};l=Object.freeze(s),n&&(n.public[r]=a),c.get(r)?.forEach(u=>u(a,i)),f.forEach(u=>u(r,a,i))}catch(t){console.error("[REP] Failed to process hot reload event:",t)}}),d.addEventListener("rep:config:delete",e=>{try{let t=JSON.parse(e.data),{key:r}=t,a=l[r],i={...l};delete i[r],l=Object.freeze(i),n&&delete n.public[r],c.get(r)?.forEach(s=>s("",a)),f.forEach(s=>s(r,"",a))}catch(t){console.error("[REP] Failed to process hot reload delete:",t)}}),d.onerror=()=>{console.warn("[REP] Hot reload SSE connection lost. Will reconnect automatically.")})}function E(){c.size===0&&f.size===0&&d&&(d.close(),d=null)}var O={get:x,getSecure:A,getAll:P,verify:V,meta:j,onChange:k,onAnyChange:M},z=O;export{z as default,x as get,P as getAll,A as getSecure,j as meta,M as onAnyChange,k as onChange,O as rep,V as verify};
+/**
+ * @rep-protocol/sdk — Client SDK for the Runtime Environment Protocol.
+ *
+ * Zero-dependency, framework-agnostic SDK for reading environment variables
+ * injected by the REP gateway.
+ *
+ * PUBLIC tier variables are available synchronously via `rep.get()`.
+ * SENSITIVE tier variables require async decryption via `rep.getSecure()`.
+ *
+ * @see https://github.com/ruachtech/rep — REP-RFC-0001 §5
+ * @license Apache-2.0
+ * @version 0.1.0
+ */

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@rep-protocol/sdk",
+  "version": "0.1.2",
+  "description": "Client SDK for the Runtime Environment Protocol (REP). Zero-dependency, framework-agnostic runtime env var access for browser applications.",
+  "author": "Ruach Tech",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RuachTech/rep",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/RuachTech/rep#readme",
+  "keywords": [
+    "environment-variables",
+    "runtime-config",
+    "docker",
+    "containers",
+    "frontend",
+    "twelve-factor",
+    "spa",
+    "react",
+    "vue",
+    "svelte",
+    "angular"
+  ],
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "jsdom": "^28.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean --minify",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}