@theruntimehq/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheRuntimeHQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @theruntimehq/react
+
+[![npm version](https://img.shields.io/npm/v/@theruntimehq/react.svg)](https://www.npmjs.com/package/@theruntimehq/react)
+[![license](https://img.shields.io/npm/l/@theruntimehq/react.svg)](https://github.com/TheRuntimeHQ/runtimehq-react/blob/main/LICENSE)
+
+The official React state management SDK for [RuntimeHQ](https://theruntimehq.com). Connect your status checks directly to your React primitives.
+
+This SDK is a **pure state management SDK** with:
+- 🚫 **No visual UI components** (Customers use their own design systems).
+- 🚫 **No CSS, Tailwind, or style sheet dependencies**.
+- 🚫 **No external state libraries**.
+- ⚛️ Full support for **React 18+ and 19+**.
+- 🌐 Native compatibility with Server-Side Rendering (SSR), Vite, Next.js, and Remix.
+
+---
+
+## Installation
+
+Ensure you have `@theruntimehq/js` and React installed in your project:
+
+```bash
+npm install @theruntimehq/react @theruntimehq/js
+```
+
+---
+
+## Core Hooks & Provider APIs
+
+### 1. Global Provider (`RuntimeHQProvider`)
+
+Wrap your root application with the `RuntimeHQProvider`. It internally manages a single `RuntimeHQClient` and handles global state subscription and cleanup.
+
+```tsx
+import { RuntimeHQProvider } from "@theruntimehq/react";
+
+export default function Root() {
+  return (
+    <RuntimeHQProvider 
+      runtimeKey="rt_prod_your_key_here" 
+      intervalSeconds={15}
+    >
+      <App />
+    </RuntimeHQProvider>
+  );
+}
+```
+
+#### Provider Props
+| Prop | Type | Required | Default | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `runtimeKey` | `string` | **Yes** | - | Your RuntimeHQ API status key (must start with `rt_prod_` or `rt_test_`). |
+| `intervalSeconds` | `number` | No | `15` | Polling interval for updates in seconds. |
+
+---
+
+### 2. Context Hook (`useRuntimeHQ`)
+
+Consume the global status state anywhere inside the provider.
+
+```tsx
+import { useRuntimeHQ, isOperational } from "@theruntimehq/react";
+
+function StatusBanner() {
+  const { runtime, loading, error } = useRuntimeHQ();
+
+  if (loading) return <div>Checking status...</div>;
+  if (error) return <div>Error fetching status: {error.message}</div>;
+  if (!runtime || isOperational(runtime)) return null;
+
+  return (
+    <div className={`banner ${runtime.state.toLowerCase()}`}>
+      ⚠️ {runtime.message}
+    </div>
+  );
+}
+```
+
+#### Return Value
+```typescript
+interface RuntimeHQContextValue {
+  runtime: RuntimeResponse | null; // Detailed status info or null before first fetch
+  loading: boolean;                // true until the first fetch (success or failure) completes
+  error: Error | null;             // Captured network or validation error (if any)
+}
+```
+
+> [!IMPORTANT]
+> If `useRuntimeHQ` is invoked outside a `<RuntimeHQProvider>`, it throws a descriptive error:
+> `useRuntimeHQ must be used within a RuntimeHQProvider`
+
+---
+
+### 3. Standalone Direct Hook (`useRuntimeHQState`)
+
+If you want to read runtime status inside isolated widgets without setting up a context provider at the root level, use `useRuntimeHQState`. It shares the same state management and cleanup logic as the provider.
+
+```tsx
+import { useRuntimeHQState } from "@theruntimehq/react";
+
+function IndependentWidget() {
+  const { runtime, loading, error } = useRuntimeHQState({
+    runtimeKey: "rt_prod_your_key_here",
+    intervalSeconds: 30,
+  });
+
+  if (loading) return <Spinner />;
+  return <div>State: {runtime?.state}</div>;
+}
+```
+
+---
+
+## Convenience Helpers
+
+Quickly determine states using utility checkers. These accept either the full `RuntimeResponse` object, the `RuntimeState` string, or `null`/`undefined`.
+
+```typescript
+import { 
+  isOperational, 
+  isMaintenance, 
+  isDegraded, 
+  isOutage 
+} from "@theruntimehq/react";
+
+// Usage
+isOperational(runtime)  // returns boolean
+isMaintenance(runtime)  // returns boolean
+isDegraded(runtime)     // returns boolean
+isOutage(runtime)       // returns boolean
+```
+
+---
+
+## Server Rendering (SSR) & Next.js App Router Integration
+
+To avoid layout shifts and flashes of loading states on initial load, fetch the status server-side using the underlying `@theruntimehq/js` SDK directly, and render a static warning component on the server:
+
+```tsx
+// src/app/page.tsx (Next.js Server Component)
+import { RuntimeHQClient } from "@theruntimehq/js";
+import ClientSidePoller from "./ClientSidePoller";
+
+export default async function Page() {
+  const client = new RuntimeHQClient({ runtimeKey: process.env.RUNTIMEHQ_KEY! });
+  let initialRuntime = null;
+
+  try {
+    initialRuntime = await client.getRuntime();
+  } catch (err) {
+    // Fail-open: ignore server-side fetch errors during build/request
+    console.error("Failed to check status during SSR:", err);
+  }
+
+  return (
+    <main>
+      {/* 1. SSR Static Layout (Zero layout shift on load) */}
+      {initialRuntime && initialRuntime.state !== "OPERATIONAL" && (
+        <div className="banner">
+          ⚠️ {initialRuntime.message}
+        </div>
+      )}
+
+      {/* 2. Client Side Poller (Handles live updates) */}
+      <ClientSidePoller initialData={initialRuntime} />
+    </main>
+  );
+}
+```
+
+```tsx
+// src/app/ClientSidePoller.tsx (Client Component)
+"use client";
+
+import { useRuntimeHQState } from "@theruntimehq/react";
+import type { RuntimeResponse } from "@theruntimehq/react";
+
+interface ClientSidePollerProps {
+  initialData: RuntimeResponse | null;
+}
+
+export default function ClientSidePoller({ initialData }: ClientSidePollerProps) {
+  const { runtime } = useRuntimeHQState({
+    runtimeKey: "rt_prod_your_key_here",
+    intervalSeconds: 15,
+  });
+
+  // Hydrate client-side with server-fetched data initially
+  const currentRuntime = runtime || initialData;
+
+  if (!currentRuntime || currentRuntime.state === "OPERATIONAL") return null;
+
+  return (
+    <div className="interactive-status">
+      Status is {currentRuntime.state} (Polled: {runtime ? "Yes" : "No"})
+    </div>
+  );
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,54 @@
+import React from 'react';
+import { RuntimeResponse, RuntimeState } from '@theruntimehq/js';
+export { RuntimeHQClientOptions, RuntimeResponse, RuntimeSourceType, RuntimeState, WatchRuntimeOptions } from '@theruntimehq/js';
+
+interface RuntimeHQProviderProps {
+    runtimeKey: string;
+    intervalSeconds?: number;
+    children: React.ReactNode;
+}
+/**
+ * Context Provider that manages a global RuntimeHQ client subscription and polling loop,
+ * making the status state available to all child components using `useRuntimeHQ()`.
+ */
+declare function RuntimeHQProvider({ runtimeKey, intervalSeconds, children, }: RuntimeHQProviderProps): React.JSX.Element;
+
+interface RuntimeHQContextValue {
+    runtime: RuntimeResponse | null;
+    loading: boolean;
+    error: Error | null;
+}
+
+/**
+ * Accesses the global RuntimeHQ status check context.
+ * Must be used within a `<RuntimeHQProvider>`.
+ */
+declare function useRuntimeHQ(): RuntimeHQContextValue;
+
+interface UseRuntimeHQStateOptions {
+    runtimeKey: string;
+    intervalSeconds?: number;
+}
+/**
+ * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.
+ */
+declare function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue;
+
+/**
+ * Checks if the application runtime status is OPERATIONAL.
+ */
+declare function isOperational(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean;
+/**
+ * Checks if the application runtime status is MAINTENANCE.
+ */
+declare function isMaintenance(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean;
+/**
+ * Checks if the application runtime status is DEGRADED.
+ */
+declare function isDegraded(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean;
+/**
+ * Checks if the application runtime status is OUTAGE.
+ */
+declare function isOutage(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean;
+
+export { type RuntimeHQContextValue, RuntimeHQProvider, type RuntimeHQProviderProps, type UseRuntimeHQStateOptions, isDegraded, isMaintenance, isOperational, isOutage, useRuntimeHQ, useRuntimeHQState };

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import React from 'react';
+import { RuntimeResponse, RuntimeState } from '@theruntimehq/js';
+export { RuntimeHQClientOptions, RuntimeResponse, RuntimeSourceType, RuntimeState, WatchRuntimeOptions } from '@theruntimehq/js';
+
+interface RuntimeHQProviderProps {
+    runtimeKey: string;
+    intervalSeconds?: number;
+    children: React.ReactNode;
+}
+/**
+ * Context Provider that manages a global RuntimeHQ client subscription and polling loop,
+ * making the status state available to all child components using `useRuntimeHQ()`.
+ */
+declare function RuntimeHQProvider({ runtimeKey, intervalSeconds, children, }: RuntimeHQProviderProps): React.JSX.Element;
+
+interface RuntimeHQContextValue {
+    runtime: RuntimeResponse | null;
+    loading: boolean;
+    error: Error | null;
+}
+
+/**
+ * Accesses the global RuntimeHQ status check context.
+ * Must be used within a `<RuntimeHQProvider>`.
+ */
+declare function useRuntimeHQ(): RuntimeHQContextValue;
+
+interface UseRuntimeHQStateOptions {
+    runtimeKey: string;
+    intervalSeconds?: number;
+}
+/**
+ * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.
+ */
+declare function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue;
+
+/**
+ * Checks if the application runtime status is OPERATIONAL.
+ */
+declare function isOperational(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean;
+/**
+ * Checks if the application runtime status is MAINTENANCE.
+ */
+declare function isMaintenance(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean;
+/**
+ * Checks if the application runtime status is DEGRADED.
+ */
+declare function isDegraded(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean;
+/**
+ * Checks if the application runtime status is OUTAGE.
+ */
+declare function isOutage(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean;
+
+export { type RuntimeHQContextValue, RuntimeHQProvider, type RuntimeHQProviderProps, type UseRuntimeHQStateOptions, isDegraded, isMaintenance, isOperational, isOutage, useRuntimeHQ, useRuntimeHQState };

package/dist/index.js

@@ -0,0 +1,107 @@
+'use strict';
+
+var react = require('react');
+var js = require('@theruntimehq/js');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/context/index.ts
+var RuntimeHQContext = react.createContext(null);
+function useRuntimeHQState(options) {
+  const { runtimeKey, intervalSeconds = 15 } = options;
+  const [client, clientInitError] = react.useMemo(() => {
+    if (!runtimeKey) {
+      return [null, new Error("runtimeKey is required")];
+    }
+    try {
+      return [new js.RuntimeHQClient({ runtimeKey }), null];
+    } catch (err) {
+      return [null, err instanceof Error ? err : new Error(String(err))];
+    }
+  }, [runtimeKey]);
+  const [runtime, setRuntime] = react.useState(null);
+  const [error, setError] = react.useState(clientInitError || null);
+  const [loading, setLoading] = react.useState(!clientInitError);
+  react.useEffect(() => {
+    if (clientInitError) {
+      setError(clientInitError);
+      setLoading(false);
+      return;
+    }
+    if (!client) {
+      return;
+    }
+    setRuntime(null);
+    setError(null);
+    setLoading(true);
+    let active = true;
+    const unsubscribe = client.watchRuntime({
+      intervalSeconds,
+      onUpdate: (data) => {
+        if (active) {
+          setRuntime(data);
+          setError(null);
+          setLoading(false);
+        }
+      },
+      onError: (err) => {
+        if (active) {
+          setError(err);
+          setLoading(false);
+        }
+      }
+    });
+    return () => {
+      active = false;
+      unsubscribe();
+    };
+  }, [client, clientInitError, intervalSeconds]);
+  return {
+    runtime,
+    loading,
+    error
+  };
+}
+function RuntimeHQProvider({
+  runtimeKey,
+  intervalSeconds,
+  children
+}) {
+  const value = useRuntimeHQState({ runtimeKey, intervalSeconds });
+  return /* @__PURE__ */ jsxRuntime.jsx(RuntimeHQContext.Provider, { value, children });
+}
+function useRuntimeHQ() {
+  const context = react.useContext(RuntimeHQContext);
+  if (!context) {
+    throw new Error("useRuntimeHQ must be used within a RuntimeHQProvider");
+  }
+  return context;
+}
+
+// src/helpers/index.ts
+function getState(runtime) {
+  if (!runtime) return null;
+  if (typeof runtime === "string") return runtime;
+  return runtime.state || null;
+}
+function isOperational(runtime) {
+  return getState(runtime) === "OPERATIONAL";
+}
+function isMaintenance(runtime) {
+  return getState(runtime) === "MAINTENANCE";
+}
+function isDegraded(runtime) {
+  return getState(runtime) === "DEGRADED";
+}
+function isOutage(runtime) {
+  return getState(runtime) === "OUTAGE";
+}
+
+exports.RuntimeHQProvider = RuntimeHQProvider;
+exports.isDegraded = isDegraded;
+exports.isMaintenance = isMaintenance;
+exports.isOperational = isOperational;
+exports.isOutage = isOutage;
+exports.useRuntimeHQ = useRuntimeHQ;
+exports.useRuntimeHQState = useRuntimeHQState;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context/index.ts","../src/hooks/useRuntimeHQState.ts","../src/provider/index.tsx","../src/hooks/useRuntimeHQ.ts","../src/helpers/index.ts"],"names":["createContext","useMemo","RuntimeHQClient","useState","useEffect","jsx","useContext"],"mappings":"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","file":"index.js","sourcesContent":["\"use client\";\n\nimport { createContext } from \"react\";\nimport { RuntimeHQContextValue } from \"../types\";\n\nexport const RuntimeHQContext = createContext<RuntimeHQContextValue | null>(null);\n","\"use client\";\n\nimport { useState, useEffect, useMemo } from \"react\";\nimport { RuntimeHQClient } from \"@theruntimehq/js\";\nimport { RuntimeResponse, RuntimeHQContextValue } from \"../types\";\n\nexport interface UseRuntimeHQStateOptions {\n  runtimeKey: string;\n  intervalSeconds?: number;\n}\n\n/**\n * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.\n */\nexport function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue {\n  const { runtimeKey, intervalSeconds = 15 } = options;\n\n  // Safely instantiate RuntimeHQClient\n  const [client, clientInitError] = useMemo(() => {\n    if (!runtimeKey) {\n      return [null, new Error(\"runtimeKey is required\")] as const;\n    }\n    try {\n      return [new RuntimeHQClient({ runtimeKey }), null] as const;\n    } catch (err) {\n      return [null, err instanceof Error ? err : new Error(String(err))] as const;\n    }\n  }, [runtimeKey]);\n\n  const [runtime, setRuntime] = useState<RuntimeResponse | null>(null);\n  const [error, setError] = useState<Error | null>(clientInitError || null);\n  const [loading, setLoading] = useState<boolean>(!clientInitError);\n\n  useEffect(() => {\n    if (clientInitError) {\n      setError(clientInitError);\n      setLoading(false);\n      return;\n    }\n\n    if (!client) {\n      return;\n    }\n\n    // Reset states when the client or key changes\n    setRuntime(null);\n    setError(null);\n    setLoading(true);\n\n    let active = true;\n\n    const unsubscribe = client.watchRuntime({\n      intervalSeconds,\n      onUpdate: (data) => {\n        if (active) {\n          setRuntime(data);\n          setError(null);\n          setLoading(false);\n        }\n      },\n      onError: (err) => {\n        if (active) {\n          setError(err);\n          setLoading(false);\n        }\n      },\n    });\n\n    return () => {\n      active = false;\n      unsubscribe();\n    };\n  }, [client, clientInitError, intervalSeconds]);\n\n  return {\n    runtime,\n    loading,\n    error,\n  };\n}\n","\"use client\";\n\nimport React from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { useRuntimeHQState } from \"../hooks/useRuntimeHQState\";\n\nexport interface RuntimeHQProviderProps {\n  runtimeKey: string;\n  intervalSeconds?: number;\n  children: React.ReactNode;\n}\n\n/**\n * Context Provider that manages a global RuntimeHQ client subscription and polling loop,\n * making the status state available to all child components using `useRuntimeHQ()`.\n */\nexport function RuntimeHQProvider({\n  runtimeKey,\n  intervalSeconds,\n  children,\n}: RuntimeHQProviderProps) {\n  const value = useRuntimeHQState({ runtimeKey, intervalSeconds });\n\n  return (\n    <RuntimeHQContext.Provider value={value}>\n      {children}\n    </RuntimeHQContext.Provider>\n  );\n}\n","\"use client\";\n\nimport { useContext } from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { RuntimeHQContextValue } from \"../types\";\n\n/**\n * Accesses the global RuntimeHQ status check context.\n * Must be used within a `<RuntimeHQProvider>`.\n */\nexport function useRuntimeHQ(): RuntimeHQContextValue {\n  const context = useContext(RuntimeHQContext);\n  if (!context) {\n    throw new Error(\"useRuntimeHQ must be used within a RuntimeHQProvider\");\n  }\n  return context;\n}\n","import { RuntimeResponse, RuntimeState } from \"../types\";\n\nfunction getState(runtime: RuntimeResponse | RuntimeState | null | undefined): RuntimeState | null {\n  if (!runtime) return null;\n  if (typeof runtime === \"string\") return runtime;\n  return runtime.state || null;\n}\n\n/**\n * Checks if the application runtime status is OPERATIONAL.\n */\nexport function isOperational(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean {\n  return getState(runtime) === \"OPERATIONAL\";\n}\n\n/**\n * Checks if the application runtime status is MAINTENANCE.\n */\nexport function isMaintenance(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean {\n  return getState(runtime) === \"MAINTENANCE\";\n}\n\n/**\n * Checks if the application runtime status is DEGRADED.\n */\nexport function isDegraded(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean {\n  return getState(runtime) === \"DEGRADED\";\n}\n\n/**\n * Checks if the application runtime status is OUTAGE.\n */\nexport function isOutage(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean {\n  return getState(runtime) === \"OUTAGE\";\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,99 @@
+import { createContext, useMemo, useState, useEffect, useContext } from 'react';
+import { RuntimeHQClient } from '@theruntimehq/js';
+import { jsx } from 'react/jsx-runtime';
+
+// src/context/index.ts
+var RuntimeHQContext = createContext(null);
+function useRuntimeHQState(options) {
+  const { runtimeKey, intervalSeconds = 15 } = options;
+  const [client, clientInitError] = useMemo(() => {
+    if (!runtimeKey) {
+      return [null, new Error("runtimeKey is required")];
+    }
+    try {
+      return [new RuntimeHQClient({ runtimeKey }), null];
+    } catch (err) {
+      return [null, err instanceof Error ? err : new Error(String(err))];
+    }
+  }, [runtimeKey]);
+  const [runtime, setRuntime] = useState(null);
+  const [error, setError] = useState(clientInitError || null);
+  const [loading, setLoading] = useState(!clientInitError);
+  useEffect(() => {
+    if (clientInitError) {
+      setError(clientInitError);
+      setLoading(false);
+      return;
+    }
+    if (!client) {
+      return;
+    }
+    setRuntime(null);
+    setError(null);
+    setLoading(true);
+    let active = true;
+    const unsubscribe = client.watchRuntime({
+      intervalSeconds,
+      onUpdate: (data) => {
+        if (active) {
+          setRuntime(data);
+          setError(null);
+          setLoading(false);
+        }
+      },
+      onError: (err) => {
+        if (active) {
+          setError(err);
+          setLoading(false);
+        }
+      }
+    });
+    return () => {
+      active = false;
+      unsubscribe();
+    };
+  }, [client, clientInitError, intervalSeconds]);
+  return {
+    runtime,
+    loading,
+    error
+  };
+}
+function RuntimeHQProvider({
+  runtimeKey,
+  intervalSeconds,
+  children
+}) {
+  const value = useRuntimeHQState({ runtimeKey, intervalSeconds });
+  return /* @__PURE__ */ jsx(RuntimeHQContext.Provider, { value, children });
+}
+function useRuntimeHQ() {
+  const context = useContext(RuntimeHQContext);
+  if (!context) {
+    throw new Error("useRuntimeHQ must be used within a RuntimeHQProvider");
+  }
+  return context;
+}
+
+// src/helpers/index.ts
+function getState(runtime) {
+  if (!runtime) return null;
+  if (typeof runtime === "string") return runtime;
+  return runtime.state || null;
+}
+function isOperational(runtime) {
+  return getState(runtime) === "OPERATIONAL";
+}
+function isMaintenance(runtime) {
+  return getState(runtime) === "MAINTENANCE";
+}
+function isDegraded(runtime) {
+  return getState(runtime) === "DEGRADED";
+}
+function isOutage(runtime) {
+  return getState(runtime) === "OUTAGE";
+}
+
+export { RuntimeHQProvider, isDegraded, isMaintenance, isOperational, isOutage, useRuntimeHQ, useRuntimeHQState };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context/index.ts","../src/hooks/useRuntimeHQState.ts","../src/provider/index.tsx","../src/hooks/useRuntimeHQ.ts","../src/helpers/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["\"use client\";\n\nimport { createContext } from \"react\";\nimport { RuntimeHQContextValue } from \"../types\";\n\nexport const RuntimeHQContext = createContext<RuntimeHQContextValue | null>(null);\n","\"use client\";\n\nimport { useState, useEffect, useMemo } from \"react\";\nimport { RuntimeHQClient } from \"@theruntimehq/js\";\nimport { RuntimeResponse, RuntimeHQContextValue } from \"../types\";\n\nexport interface UseRuntimeHQStateOptions {\n  runtimeKey: string;\n  intervalSeconds?: number;\n}\n\n/**\n * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.\n */\nexport function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue {\n  const { runtimeKey, intervalSeconds = 15 } = options;\n\n  // Safely instantiate RuntimeHQClient\n  const [client, clientInitError] = useMemo(() => {\n    if (!runtimeKey) {\n      return [null, new Error(\"runtimeKey is required\")] as const;\n    }\n    try {\n      return [new RuntimeHQClient({ runtimeKey }), null] as const;\n    } catch (err) {\n      return [null, err instanceof Error ? err : new Error(String(err))] as const;\n    }\n  }, [runtimeKey]);\n\n  const [runtime, setRuntime] = useState<RuntimeResponse | null>(null);\n  const [error, setError] = useState<Error | null>(clientInitError || null);\n  const [loading, setLoading] = useState<boolean>(!clientInitError);\n\n  useEffect(() => {\n    if (clientInitError) {\n      setError(clientInitError);\n      setLoading(false);\n      return;\n    }\n\n    if (!client) {\n      return;\n    }\n\n    // Reset states when the client or key changes\n    setRuntime(null);\n    setError(null);\n    setLoading(true);\n\n    let active = true;\n\n    const unsubscribe = client.watchRuntime({\n      intervalSeconds,\n      onUpdate: (data) => {\n        if (active) {\n          setRuntime(data);\n          setError(null);\n          setLoading(false);\n        }\n      },\n      onError: (err) => {\n        if (active) {\n          setError(err);\n          setLoading(false);\n        }\n      },\n    });\n\n    return () => {\n      active = false;\n      unsubscribe();\n    };\n  }, [client, clientInitError, intervalSeconds]);\n\n  return {\n    runtime,\n    loading,\n    error,\n  };\n}\n","\"use client\";\n\nimport React from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { useRuntimeHQState } from \"../hooks/useRuntimeHQState\";\n\nexport interface RuntimeHQProviderProps {\n  runtimeKey: string;\n  intervalSeconds?: number;\n  children: React.ReactNode;\n}\n\n/**\n * Context Provider that manages a global RuntimeHQ client subscription and polling loop,\n * making the status state available to all child components using `useRuntimeHQ()`.\n */\nexport function RuntimeHQProvider({\n  runtimeKey,\n  intervalSeconds,\n  children,\n}: RuntimeHQProviderProps) {\n  const value = useRuntimeHQState({ runtimeKey, intervalSeconds });\n\n  return (\n    <RuntimeHQContext.Provider value={value}>\n      {children}\n    </RuntimeHQContext.Provider>\n  );\n}\n","\"use client\";\n\nimport { useContext } from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { RuntimeHQContextValue } from \"../types\";\n\n/**\n * Accesses the global RuntimeHQ status check context.\n * Must be used within a `<RuntimeHQProvider>`.\n */\nexport function useRuntimeHQ(): RuntimeHQContextValue {\n  const context = useContext(RuntimeHQContext);\n  if (!context) {\n    throw new Error(\"useRuntimeHQ must be used within a RuntimeHQProvider\");\n  }\n  return context;\n}\n","import { RuntimeResponse, RuntimeState } from \"../types\";\n\nfunction getState(runtime: RuntimeResponse | RuntimeState | null | undefined): RuntimeState | null {\n  if (!runtime) return null;\n  if (typeof runtime === \"string\") return runtime;\n  return runtime.state || null;\n}\n\n/**\n * Checks if the application runtime status is OPERATIONAL.\n */\nexport function isOperational(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean {\n  return getState(runtime) === \"OPERATIONAL\";\n}\n\n/**\n * Checks if the application runtime status is MAINTENANCE.\n */\nexport function isMaintenance(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean {\n  return getState(runtime) === \"MAINTENANCE\";\n}\n\n/**\n * Checks if the application runtime status is DEGRADED.\n */\nexport function isDegraded(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean {\n  return getState(runtime) === \"DEGRADED\";\n}\n\n/**\n * Checks if the application runtime status is OUTAGE.\n */\nexport function isOutage(runtime: RuntimeResponse | RuntimeState | null | undefined): boolean {\n  return getState(runtime) === \"OUTAGE\";\n}\n"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@theruntimehq/react",
+  "version": "0.1.0",
+  "description": "Official React SDK for RuntimeHQ status checking and monitoring.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "runtimehq",
+    "status",
+    "monitoring",
+    "sdk",
+    "react",
+    "hooks"
+  ],
+  "author": "RuntimeHQ",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheRuntimeHQ/runtimehq-react.git"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "@theruntimehq/js": "^0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^15.0.7",
+    "@types/react": "^18.2.79",
+    "@types/react-dom": "^18.2.25",
+    "jsdom": "^24.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  }
+}