@reflag/rest-api-sdk 0.0.1

package/README.md

@@ -0,0 +1,173 @@
+# @reflag/rest-api-sdk (beta)
+
+Typed SDK for Reflag's REST API.
+
+## Installation
+
+```bash
+npm install @reflag/rest-api-sdk
+# or
+yarn add @reflag/rest-api-sdk
+```
+
+## Create a client
+
+All requests require a Reflag API key.
+
+```typescript
+import { Api } from "@reflag/rest-api-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/rest-api-sdk`
+
+Core method groups:
+
+- Applications: `listApps`, `getApp`
+- Environments: `listEnvironments`, `getEnvironment`
+- Flags: `listFlags`, `createFlag`, `updateFlag`, `getFlagTargeting`
+- User/company evaluation: `getUserFlags`, `updateUserFlags`, `getCompanyFlags`, `updateCompanyFlags`
+
+## Quick start
+
+```typescript
+const apps = await api.listApps();
+console.log(apps.data);
+
+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);
+}
+```
+
+## App-scoped client
+
+If most calls are for one app, use `createAppClient` to avoid repeating `appId`.
+
+```typescript
+import { createAppClient } from "@reflag/rest-api-sdk";
+
+const appApi = createAppClient("app-123", {
+  accessToken: process.env.REFLAG_API_KEY,
+});
+
+const environments = await appApi.listEnvironments({
+  sortBy: "order",
+  sortOrder: "asc",
+});
+
+const flags = await appApi.listFlags({});
+```
+
+## 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,
+});
+
+await api.updateFlag({
+  appId: "app-123",
+  flagId: created.flag.id,
+  name: "New checkout experience",
+  ownerUserId: null,
+});
+```
+
+### 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);
+```
+
+### Toggle a user flag
+
+Use `true` to explicitly target on, and `null` to remove specific targeting.
+
+```typescript
+await api.updateUserFlags({
+  appId: "app-123",
+  envId: "env-456",
+  userId: "user-1",
+  updates: [{ flagKey: "new-checkout", specificTargetValue: true }],
+});
+```
+
+### Read and update company flags
+
+```typescript
+const companyFlags = await api.getCompanyFlags({
+  appId: "app-123",
+  envId: "env-456",
+  companyId: "company-1",
+});
+
+await api.updateCompanyFlags({
+  appId: "app-123",
+  envId: "env-456",
+  companyId: "company-1",
+  updates: [{ flagKey: "new-checkout", specificTargetValue: null }],
+});
+```
+
+## Error handling
+
+The SDK throws `ReflagApiError` for non-2xx API responses.
+
+```typescript
+import { ReflagApiError } from "@reflag/rest-api-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/rest-api-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,119 @@
+"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 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) => {
+                if (arg1 && typeof arg1 === "object" && !Array.isArray(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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"}