@startsimpli/api 0.5.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/api",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Type-safe Django REST API client for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/constants/endpoints.ts

@@ -49,4 +49,6 @@ export const ENDPOINTS = {
   FUNNEL_RUN_BY_ID: (runId: string) => `api/v1/funnel-runs/${runId}`,
   FUNNEL_RUN_CANCEL: (runId: string) => `api/v1/funnel-runs/${runId}/cancel`,
   FUNNEL_RUNS_GLOBAL: 'api/v1/funnel-runs',
+  // Companies / Feature flags
+  FEATURE_FLAGS: 'api/v1/companies/feature-flags',
 } as const;

package/src/index.ts

@@ -19,6 +19,10 @@ export type { Message, MessageStatus as MessageApiStatus, MessageRecipient, Mess
 export { FunnelsApi, isFunnelRunConflict, isFunnelValidationError } from './lib/funnels-api';
 export type { FunnelPreviewResult, FunnelRunFilters, FunnelTemplate } from './lib/funnels-api';
 
+// Feature flags
+export { FeatureFlagsApi, FeatureFlagProvider, useFeatureFlags } from './lib/feature-flags';
+export type { FeatureFlags, FeatureFlagsResponse, FeatureFlagContextValue, FeatureFlagProviderProps } from './lib/feature-flags';
+
 // Fetch wrapper
 export { FetchWrapper } from './lib/fetch-wrapper';
 export type { FetchWrapperConfig } from './lib/fetch-wrapper';
@@ -121,6 +125,7 @@ import { EntitiesApi } from './lib/entities-api';
 import { WorkflowsApi } from './lib/workflows-api';
 import { MessagesApi } from './lib/messages-api';
 import { FunnelsApi } from './lib/funnels-api';
+import { FeatureFlagsApi } from './lib/feature-flags';
 
 import type { ApiClientConfig } from './lib/api-client';
 
@@ -139,5 +144,6 @@ export function createStartSimpliApi(config: ApiClientConfig = {}) {
     workflows: new WorkflowsApi(client),
     messages: new MessagesApi(client),
     funnels: new FunnelsApi(client),
+    featureFlags: new FeatureFlagsApi(client),
   };
 }

package/src/lib/feature-flags.ts

@@ -0,0 +1,124 @@
+'use client'
+
+/**
+ * Feature flags API client and React primitives.
+ *
+ * Flags are stored per-company in the Django backend (Company.settings.feature_flags).
+ * Default behavior is fail-closed: if a flag is not set, the feature is OFF.
+ * A company must explicitly enable features via Django admin or API.
+ *
+ * Convention:
+ *   section_<name>  – controls entire sidebar section visibility
+ *   feature_<name>  – controls individual feature availability
+ */
+
+import { createElement, createContext, useContext, useState, useEffect, useCallback } from 'react';
+import type { ReactNode } from 'react';
+import { ENDPOINTS } from '../constants/endpoints';
+import type { ApiClient } from './api-client';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type FeatureFlags = Record<string, boolean>;
+
+export interface FeatureFlagsResponse {
+  flags: FeatureFlags;
+}
+
+// ---------------------------------------------------------------------------
+// API class (used by createStartSimpliApi)
+// ---------------------------------------------------------------------------
+
+export class FeatureFlagsApi {
+  constructor(private client: ApiClient) {}
+
+  /** Fetch all flags for the current user's company. */
+  async getFlags(): Promise<FeatureFlags> {
+    const res = await this.client.get<FeatureFlagsResponse>(ENDPOINTS.FEATURE_FLAGS);
+    return res.flags;
+  }
+
+  /** Merge-update flags (admin only). Omitted flags are unchanged. */
+  async updateFlags(flags: Partial<FeatureFlags>): Promise<FeatureFlags> {
+    const res = await this.client.patch<FeatureFlagsResponse>(ENDPOINTS.FEATURE_FLAGS, { flags });
+    return res.flags;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// React context + provider + hook
+// ---------------------------------------------------------------------------
+
+export interface FeatureFlagContextValue {
+  /** Raw flag map. Missing keys are treated as `false` (fail-closed). */
+  flags: FeatureFlags;
+  /** True while the initial fetch is in-flight. */
+  isLoading: boolean;
+  /** Check a single flag. Returns `false` when flag is absent (fail-closed). */
+  isEnabled: (flag: string) => boolean;
+  /** Convenience: check `section_<name>` flag. */
+  isSectionEnabled: (sectionTitle: string) => boolean;
+}
+
+const FeatureFlagContext = createContext<FeatureFlagContextValue>({
+  flags: {},
+  isLoading: true,
+  isEnabled: () => false,
+  isSectionEnabled: () => false,
+});
+
+export interface FeatureFlagProviderProps {
+  children: ReactNode;
+  /** Injected fetcher so the provider is decoupled from a specific ApiClient instance. */
+  fetchFlags: () => Promise<FeatureFlags>;
+}
+
+/**
+ * Wrap your authenticated layout with this provider.
+ * It fetches flags once on mount and makes them available via `useFeatureFlags()`.
+ */
+export function FeatureFlagProvider({ children, fetchFlags }: FeatureFlagProviderProps) {
+  // null = not yet loaded (fail-open while loading or on error)
+  // Record = API responded with flags (fail-closed for missing keys)
+  const [flags, setFlags] = useState<FeatureFlags | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    fetchFlags()
+      .then((f) => { if (!cancelled) setFlags(f); })
+      .catch(() => { if (!cancelled) setFlags(null); }) // network error = fail-open
+      .finally(() => { if (!cancelled) setIsLoading(false); });
+    return () => { cancelled = true; };
+  }, [fetchFlags]);
+
+  const isEnabled = useCallback(
+    (flag: string) => {
+      if (flags === null) return true; // API unreachable — fail-open
+      return flags[flag] ?? false;     // API responded — fail-closed
+    },
+    [flags],
+  );
+
+  const isSectionEnabled = useCallback(
+    (sectionTitle: string) => {
+      if (flags === null) return true; // API unreachable — fail-open
+      const key = `section_${sectionTitle.toLowerCase()}`;
+      return flags[key] ?? false;      // API responded — fail-closed
+    },
+    [flags],
+  );
+
+  return createElement(
+    FeatureFlagContext.Provider,
+    { value: { flags: flags ?? {}, isLoading, isEnabled, isSectionEnabled } },
+    children,
+  );
+}
+
+/** Access feature flags anywhere below FeatureFlagProvider. */
+export function useFeatureFlags(): FeatureFlagContextValue {
+  return useContext(FeatureFlagContext);
+}