@reflag/management-sdk 0.0.3

package/README.md

@@ -0,0 +1,319 @@
+# @reflag/management-sdk (beta)
+
+Typed SDK for interacting with Reflag’s Management API.
+
+Use `@reflag/management-sdk` to programmatically manage feature flags such as listing flags, and enabling or disabling them for specific users or companies.
+
+For a practical example of what you can build, see the [Customer Admin Panel](https://github.com/reflagcom/javascript/blob/main/packages/rest-api-sdk/examples/customer-admin-panel/README.md) example app.
+
+## Installation
+
+```bash
+npm i @reflag/management-sdk
+# or
+yarn add @reflag/management-sdk
+```
+
+## Create a client
+
+Initialize the SDK with a [Reflag Management API Key](https://app.reflag.com/env-current/settings/org-api-access).
+
+```typescript
+import { Api } from "@reflag/management-sdk";
+
+const api = new Api({
+  accessToken: process.env.REFLAG_API_KEY,
+});
+```
+
+## API surface
+
+Main exports:
+
+- `Api`: base client
+- `createAppClient(appId, config)`: app-scoped client
+- `ReflagApiError`: normalized API error type
+- Generated request/response types and models from `@reflag/management-sdk`
+
+Core method groups:
+
+- Applications: `listApps`, `getApp`
+- Environments: `listEnvironments`, `getEnvironment`
+- Flags: `listFlags`, `createFlag`, `updateFlag`
+- User/company evaluation: `getUserFlags`, `updateUserFlags`, `getCompanyFlags`, `updateCompanyFlags`
+
+## Quick start
+
+```typescript
+const apps = await api.listApps();
+console.log(apps.data);
+// [
+//   {
+//     "org": { "id": "org-1", "name": "Acme Org" },
+//     "id": "app-123",
+//     "name": "Acme App",
+//     "demo": false,
+//     "flagKeyFormat": "kebabCaseLower",
+//     "environments": [
+//       { "id": "env-123", "name": "Development", "isProduction": false, "order": 0 },
+//       { "id": "env-456", "name": "Production", "isProduction": true, "order": 1 }
+//     ]
+//   }
+// ]
+
+const app = apps.data[0];
+const appId = app?.id;
+
+if (appId) {
+  const environments = await api.listEnvironments({
+    appId,
+    sortBy: "order",
+    sortOrder: "asc",
+  });
+
+  console.log(environments.data);
+  // [
+  //   { "id": "env-456", "name": "Production", "isProduction": true, "order": 1 }
+  // ]
+}
+```
+
+## App-scoped client
+
+If most calls are for one app, use `createAppClient` to avoid repeating `appId`.
+
+```typescript
+import { createAppClient } from "@reflag/management-sdk";
+
+const appApi = createAppClient("app-123", {
+  accessToken: process.env.REFLAG_API_KEY,
+});
+
+const environments = await appApi.listEnvironments({
+  sortBy: "order",
+  sortOrder: "asc",
+});
+console.log(environments.data);
+// [
+//   { "id": "env-456", "name": "Production", "isProduction": true, "order": 1 }
+// ]
+
+const flags = await appApi.listFlags({});
+console.log(flags.data);
+// [
+//   {
+//     "id": "flag-1",
+//     "key": "new-checkout",
+//     "name": "New checkout",
+//     "description": "Rollout for redesigned checkout flow",
+//     "stage": { "id": "stage-1", "name": "Beta", "color": "#4f46e5", "order": 2 },
+//     "owner": {
+//       "id": "user-99",
+//       "name": "Jane Doe",
+//       "email": "jane@acme.com",
+//       "avatarUrl": "https://example.com/avatar.png"
+//     },
+//     "archived": false,
+//     "stale": false,
+//     "permanent": false,
+//     "createdAt": "2026-03-03T09:00:00.000Z",
+//     "lastCheckAt": "2026-03-03T09:30:00.000Z",
+//     "lastTrackAt": "2026-03-03T09:31:00.000Z"
+//   }
+// ]
+```
+
+## Common workflows
+
+### Create and update a flag
+
+`createFlag` and `updateFlag` return `{ flag }` with the latest flag details.
+
+Use `null` to clear nullable fields like `description` or `ownerUserId` on update.
+
+```typescript
+const created = await api.createFlag({
+  appId: "app-123",
+  key: "new-checkout",
+  name: "New checkout",
+  description: "Rollout for redesigned checkout flow",
+  secret: false,
+});
+
+const updated = await api.updateFlag({
+  appId: "app-123",
+  flagId: created.flag.id,
+  name: "New checkout experience",
+  ownerUserId: null,
+});
+console.log(updated.flag);
+// {
+//   "id": "flag-1",
+//   "key": "new-checkout",
+//   "name": "New checkout experience",
+//   "description": "Rollout for redesigned checkout flow",
+//   "stage": { "id": "stage-1", "name": "Beta", "color": "#4f46e5", "order": 2 },
+//   "owner": {
+//     "id": "user-99",
+//     "name": "Jane Doe",
+//     "email": "jane@acme.com",
+//     "avatarUrl": "https://example.com/avatar.png"
+//   },
+//   "archived": false,
+//   "stale": false,
+//   "permanent": false,
+//   "createdAt": "2026-03-03T09:00:00.000Z",
+//   "lastCheckAt": "2026-03-03T09:35:00.000Z",
+//   "lastTrackAt": "2026-03-03T09:36:00.000Z",
+//   "rolledOutToEveryoneAt": "2026-03-10T12:00:00.000Z",
+//   "parentFlagId": "flag-parent-1"
+// }
+```
+
+### Read user flags for an environment
+
+`getUserFlags` evaluates flag results for one user in one environment and returns
+the user’s current values plus exposure/check metadata for each flag.
+
+```typescript
+const userFlags = await api.getUserFlags({
+  appId: "app-123",
+  envId: "env-456",
+  userId: "user-1",
+});
+
+console.log(userFlags.data);
+// [
+//   {
+//     "id": "flag-1",
+//     "key": "new-checkout",
+//     "name": "New checkout",
+//     "createdAt": "2026-03-03T09:00:00.000Z",
+//     "value": true,
+//     "specificTargetValue": true,
+//     "firstExposureAt": "2026-03-03T09:05:00.000Z",
+//     "lastExposureAt": "2026-03-03T09:30:00.000Z",
+//     "lastCheckAt": "2026-03-03T09:31:00.000Z",
+//     "exposureCount": 12,
+//     "firstTrackAt": "2026-03-03T09:06:00.000Z",
+//     "lastTrackAt": "2026-03-03T09:32:00.000Z",
+//     "trackCount": 5
+//   }
+// ]
+```
+
+### Toggle a user flag
+
+Use `true` to explicitly target on, and `null` to remove specific targeting.
+
+```typescript
+const updatedUserFlags = await api.updateUserFlags({
+  appId: "app-123",
+  envId: "env-456",
+  userId: "user-1",
+  updates: [{ flagKey: "new-checkout", specificTargetValue: true }],
+});
+console.log(updatedUserFlags.data);
+// [
+//   {
+//     "id": "flag-1",
+//     "key": "new-checkout",
+//     "name": "New checkout",
+//     "createdAt": "2026-03-03T09:00:00.000Z",
+//     "value": true,
+//     "specificTargetValue": true,
+//     "firstExposureAt": "2026-03-03T09:05:00.000Z",
+//     "lastExposureAt": "2026-03-03T09:35:00.000Z",
+//     "lastCheckAt": "2026-03-03T09:36:00.000Z",
+//     "exposureCount": 13,
+//     "firstTrackAt": "2026-03-03T09:06:00.000Z",
+//     "lastTrackAt": "2026-03-03T09:37:00.000Z",
+//     "trackCount": 6
+//   }
+// ]
+```
+
+### Read company flags for an environment
+
+```typescript
+const companyFlags = await api.getCompanyFlags({
+  appId: "app-123",
+  envId: "env-456",
+  companyId: "company-1",
+});
+console.log(companyFlags.data);
+// [
+//   {
+//     "id": "flag-1",
+//     "key": "new-checkout",
+//     "name": "New checkout",
+//     "createdAt": "2026-03-03T09:00:00.000Z",
+//     "value": false,
+//     "specificTargetValue": null,
+//     "firstExposureAt": null,
+//     "lastExposureAt": null,
+//     "lastCheckAt": "2026-03-03T09:31:00.000Z",
+//     "exposureCount": 0,
+//     "firstTrackAt": null,
+//     "lastTrackAt": null,
+//     "trackCount": 0
+//   }
+// ]
+```
+
+### Toggle a company flag
+
+Use `true` to explicitly target on, and `null` to remove specific targeting.
+
+```typescript
+const updatedCompanyFlags = await api.updateCompanyFlags({
+  appId: "app-123",
+  envId: "env-456",
+  companyId: "company-1",
+  // Use `null` to stop targeting the company specifically for that flag.
+  updates: [{ flagKey: "new-checkout", specificTargetValue: null }],
+});
+console.log(updatedCompanyFlags.data);
+// [
+//   {
+//     "id": "flag-1",
+//     "key": "new-checkout",
+//     "name": "New checkout",
+//     "createdAt": "2026-03-03T09:00:00.000Z",
+//     "value": false,
+//     "specificTargetValue": null,
+//     "firstExposureAt": null,
+//     "lastExposureAt": null,
+//     "lastCheckAt": "2026-03-03T09:36:00.000Z",
+//     "exposureCount": 0,
+//     "firstTrackAt": null,
+//     "lastTrackAt": null,
+//     "trackCount": 0
+//   }
+// ]
+```
+
+## Error handling
+
+The SDK throws `ReflagApiError` for non-2xx API responses.
+
+```typescript
+import { ReflagApiError } from "@reflag/management-sdk";
+
+try {
+  await api.listApps();
+} catch (error) {
+  if (error instanceof ReflagApiError) {
+    console.error(error.status, error.code, error.message, error.details);
+  }
+  throw error;
+}
+```
+
+## Example app
+
+See `packages/management-sdk/examples/customer-admin-panel/README.md` for a small Next.js app using this SDK in server actions.
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,127 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Api = exports.ReflagApiError = void 0;
+exports.createAppClient = createAppClient;
+const runtime_1 = require("./generated/runtime");
+const generated_1 = require("./generated");
+class ReflagApiError extends Error {
+    constructor(status, message, code, details) {
+        super(message);
+        this.name = "ReflagApiError";
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+exports.ReflagApiError = ReflagApiError;
+function buildApiError(response) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const status = response.status;
+        const contentType = (_a = response.headers.get("content-type")) !== null && _a !== void 0 ? _a : "";
+        let details = undefined;
+        let message = `Request failed with ${status}`;
+        let code;
+        if (contentType.includes("application/json")) {
+            try {
+                details = yield response.clone().json();
+                const maybeError = details === null || details === void 0 ? void 0 : details.error;
+                if (maybeError === null || maybeError === void 0 ? void 0 : maybeError.message) {
+                    message = maybeError.message;
+                }
+                if (maybeError === null || maybeError === void 0 ? void 0 : maybeError.code) {
+                    code = maybeError.code;
+                }
+            }
+            catch (_b) {
+                details = undefined;
+            }
+        }
+        else {
+            try {
+                const text = yield response.clone().text();
+                if (text) {
+                    details = text;
+                    message = `Request failed with ${status}: ${text}`;
+                }
+            }
+            catch (_c) {
+                details = undefined;
+            }
+        }
+        return new ReflagApiError(status, message, code, details);
+    });
+}
+class Api extends generated_1.DefaultApi {
+    constructor(config) {
+        super(new generated_1.Configuration(config));
+    }
+    request(context, initOverrides) {
+        const _super = Object.create(null, {
+            request: { get: () => super.request }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield _super.request.call(this, context, initOverrides);
+            }
+            catch (error) {
+                if (error instanceof runtime_1.ResponseError) {
+                    throw yield buildApiError(error.response);
+                }
+                throw error;
+            }
+        });
+    }
+}
+exports.Api = Api;
+function isPlainObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function scopeApiToAppId(api, appId, scopedCache = new WeakMap()) {
+    const cached = scopedCache.get(api);
+    if (cached) {
+        return cached;
+    }
+    const scopedApi = new Proxy(api, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== "function")
+                return value;
+            const wrapResult = (result) => {
+                if (result instanceof Api) {
+                    return scopeApiToAppId(result, appId, scopedCache);
+                }
+                return result;
+            };
+            return (arg1, ...rest) => {
+                const isWithMethod = typeof prop === "string" && prop.startsWith("with");
+                if (!isWithMethod && isPlainObject(arg1)) {
+                    const args = "appId" in arg1 ? arg1 : Object.assign(Object.assign({}, arg1), { appId });
+                    const result = value.call(target, args, ...rest);
+                    return wrapResult(result);
+                }
+                const result = value.call(target, arg1, ...rest);
+                return wrapResult(result);
+            };
+        },
+    });
+    scopedCache.set(api, scopedApi);
+    return scopedApi;
+}
+function createAppClient(appId, config) {
+    return scopeApiToAppId(new Api(config), appId);
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}