@jewel998/config 0.1.2 → 0.1.3

package/LICENSE

@@ -0,0 +1,84 @@
+Elastic License 2.0 (ELv2)
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+
+**Control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+**Trademark** this license does not grant any rights in the trademarks, service
+marks, brand names, or logos of the licensor.
+
+---
+
+Copyright (c) 2024-present Jyotirmoy Barman. All Rights Reserved.

package/README.md

@@ -0,0 +1,234 @@
+# @jewel998/config
+
+A free, self-hostable feature flag and remote configuration platform. Deploy to your own Firebase project. Replace LaunchDarkly at $0/month.
+
+## Features
+
+- **Feature flags** — Boolean, string, number, JSON, array value types
+- **Targeting rules** — Serve different values based on user attributes (plan, country, etc.)
+- **Segments** — Reusable audience groups with one-click targeting
+- **Percentage rollouts** — Gradually roll out features with deterministic bucketing
+- **Prerequisites** — Flag dependencies with operator support (equals, greater_than, etc.)
+- **Scheduling** — Schedule config changes for a future date/time
+- **Environments** — Separate dev/staging/production configs
+- **Audit log** — Track every change with actor, timestamp, and diff viewer
+- **Webhooks** — Notify Slack, Discord, Google Chat, MS Teams, or custom endpoints
+- **RBAC** — Viewer, Editor, Admin roles per project
+- **Server-side evaluation** — Client keys never expose targeting rules or segments
+- **SDK** — Optimistic defaults, auto-context detection, instant reads
+- **Self-hosted** — Runs entirely on Firebase free tier ($0/month)
+- **7 languages** — English, Spanish, French, Arabic, Chinese, Hindi, Japanese
+
+## Self-Hosting
+
+```bash
+# 1. Clone
+git clone https://github.com/jewel998/config && cd config
+
+# 2. Connect your Firebase project
+firebase use --add your-project-id
+
+# 3. Install and deploy
+pnpm install && firebase deploy
+```
+
+That's it. Portal, API, and hosting — all on your Firebase project.
+
+## SDK Quick Start
+
+```bash
+npm install @jewel998/config
+```
+
+```typescript
+import { initConfig, autoContext } from "@jewel998/config";
+
+const flags = initConfig({
+  clientId: "cid_xxx", // From your Portal → API Keys
+  baseUrl: "https://your-project.web.app/api", // Your Firebase URL
+  defaults: {
+    "feature.dark_mode": false,
+    "app.upload_limit": 50,
+  },
+  context: autoContext({ userId: "user_123", plan: "pro" }),
+});
+
+// Instant — returns default value, no loading state
+flags.get("feature.dark_mode"); // → false
+
+// After API responds, returns resolved value
+flags.on("updated", () => {
+  flags.get("feature.dark_mode"); // → true (matched targeting rule)
+});
+```
+
+### API Key Types
+
+| Prefix | Type   | Behavior                                                                                                            |
+| ------ | ------ | ------------------------------------------------------------------------------------------------------------------- |
+| `cid_` | Client | For frontend. API evaluates targeting server-side, returns only values. Targeting rules and segments never exposed. |
+| `svr_` | Server | For backend. API returns full flag data + segments for local evaluation via plugins.                                |
+
+The API enforces the mode based on key prefix — cannot be overridden.
+
+### Server Key (Backend)
+
+```typescript
+import { createConfig } from "@jewel998/config";
+import { targetingPlugin } from "@jewel998/config/targeting";
+import { rolloutPlugin } from "@jewel998/config/rollout";
+
+const config = createConfig({
+  clientId: "svr_xxx",
+  baseUrl: "https://your-project.web.app/api",
+  plugins: [targetingPlugin(), rolloutPlugin()],
+  context: { userId: "user_123", attributes: { plan: "pro", country: "US" } },
+});
+
+config.getFlag("feature.checkout_v2"); // Evaluated locally — no round-trip
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Your App                                            │
+│                                                     │
+│  import { initConfig } from "@jewel998/config"      │
+│  const flags = initConfig({ clientId, baseUrl })    │
+│  flags.get("feature.dark_mode") → true              │
+└──────────────────────┬──────────────────────────────┘
+                       │ POST /api/getConfig
+                       ▼
+┌──────────────────────────────────────────────────────┐
+│ Your Firebase Hosting (CDN cached)                   │
+└──────────────────────┬───────────────────────────────┘
+                       │ cache miss
+                       ▼
+┌──────────────────────────────────────────────────────┐
+│ Your Cloud Function: getConfig                       │
+│ - Validates clientId (cid_ or svr_)                 │
+│ - cid_: evaluates targeting server-side             │
+│ - svr_: returns full flag data for local eval       │
+└──────────────────────┬───────────────────────────────┘
+                       │
+                       ▼
+┌──────────────────────────────────────────────────────┐
+│ Your Firestore (configs, segments, projects)         │
+└──────────────────────────────────────────────────────┘
+                       ▲
+                       │
+┌──────────────────────┴───────────────────────────────┐
+│ Your Portal (React SPA on Firebase Hosting)          │
+│ - Create/edit feature flags and segments             │
+│ - Set targeting rules, rollouts, schedules           │
+│ - Manage team, environments, API keys                │
+│ - View audit log with diff viewer                    │
+│ - Configure webhook notifications                    │
+└──────────────────────────────────────────────────────┘
+```
+
+## API Reference
+
+### POST /api/getConfig
+
+The SDK calls this endpoint. Mode is determined by the API key prefix.
+
+**Request:**
+
+```json
+{
+  "data": {
+    "clientId": "cid_xxx",
+    "context": {
+      "userId": "user_123",
+      "attributes": { "plan": "pro", "country": "US" }
+    }
+  }
+}
+```
+
+**Response (cid\_ key) — resolved values only:**
+
+```json
+{
+  "data": { "feature.dark_mode": true, "app.upload_limit": 200 },
+  "version": "3",
+  "timestamp": "2025-01-15T09:30:00.000Z"
+}
+```
+
+**Response (svr\_ key) — full flag data + segments:**
+
+```json
+{
+  "data": {
+    "feature.dark_mode": {
+      "key": "feature.dark_mode",
+      "value": false,
+      "targetingRules": [...]
+    }
+  },
+  "segments": { "seg_beta": { "id": "...", "conditions": [...] } },
+  "version": "3",
+  "timestamp": "2025-01-15T09:30:00.000Z"
+}
+```
+
+**Errors:** `401` Invalid key · `403` Domain not allowed · `413` Context too large
+
+## Monorepo Structure
+
+```
+apps/
+  portal/      — Admin portal (React + Vite + TanStack Router)
+  landing/     — Marketing site (Astro + React)
+  docs/        — Documentation (VitePress)
+packages/
+  config/      — SDK (@jewel998/config)
+  tour/        — Tour framework (@jewel998/tour)
+functions/     — Firebase Cloud Functions (API + webhooks)
+```
+
+## Development
+
+```bash
+pnpm install                                    # Install deps
+pnpm --filter @jewel998/config-portal run dev   # Portal dev server
+pnpm --filter @jewel998/config-landing run dev  # Landing page dev
+pnpm --filter @jewel998/config run test         # SDK tests (210 passing)
+firebase deploy                                 # Deploy everything
+```
+
+## Upgrades
+
+When new versions are released, pull the latest and redeploy:
+
+```bash
+git pull origin main
+pnpm install
+firebase deploy
+```
+
+Migration guides are provided for breaking changes. Your data stays in your Firestore.
+
+## Cost
+
+The SDK polls a lightweight version endpoint (100 bytes) every 5 minutes. CDN absorbs 99%+ of these requests. Full config fetches only happen on init or version change.
+
+| Scale                | Monthly Cost | Notes                                         |
+| -------------------- | ------------ | --------------------------------------------- |
+| 1–1,000 users        | **$0**       | Well within Firebase Spark (free) tier        |
+| 1,000–50,000 users   | **$0**       | CDN handles most version polls at edge        |
+| 50,000–100,000 users | **$0–5**     | May slightly exceed free function invocations |
+| 100,000+ users       | **$5–15**    | Blaze plan with minimal overage               |
+
+Firebase free tier: 2M function invocations/month, 50K Firestore reads/day, 10GB bandwidth.
+
+## License
+
+[Elastic License 2.0](./LICENSE) — Use, modify, and self-host freely. Cannot be provided as a managed service to third parties.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions, commit conventions, and PR guidelines.

package/package.json

@@ -1,16 +1,33 @@
 {
   "name": "@jewel998/config",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "sideEffects": false,
   "description": "Free, self-hosted feature flags and remote configuration SDK",
+  "author": "Jyotirmoy Barman",
+  "homepage": "https://github.com/jewel998/config#readme",
+  "bugs": {
+    "url": "https://github.com/jewel998/config/issues"
+  },
+  "keywords": [
+    "feature-flags",
+    "remote-config",
+    "feature-toggles",
+    "self-hosted",
+    "firebase",
+    "sdk",
+    "configuration",
+    "targeting",
+    "rollout",
+    "a-b-testing"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jewel998/config.git",
     "directory": "packages/config"
   },
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "Elastic-2.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -53,7 +70,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=22.0.0"