@metrifox/react-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Metrifox
+
+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,166 @@
+# MetriFox React SDK
+
+A fully-configurable **React SDK** providing ready-to-use widgets for SaaS and billing platforms including customer portals, billing sections, and more.
+
+---
+
+## Installation
+
+```bash
+# using npm
+npm install @metrifox/react-sdk
+
+# or pnpm
+pnpm add @metrifox/react-sdk
+
+# or yarn
+yarn add @metrifox/react-sdk
+```
+
+---
+
+## Setup
+
+Before using any SDK components, initialize it once with your API key (and optional base URL).
+
+```tsx
+import { metrifoxInit } from "@metrifox/react-sdk"
+
+metrifoxInit({
+  apiKey:
+    process.env.NEXT_PUBLIC_METRIFOX_API_KEY ||
+    process.env.REACT_APP_METRIFOX_API_KEY ||
+    import.meta.env?.VITE_METRIFOX_API_KEY ||
+    "your-api-key",
+  // baseUrl: "https://api.example.com" // Optional (defaults to Metrifox Cloud)
+})
+```
+
+> Works with **React**, **Next.js**, and other frameworks using React 18+.
+
+---
+
+## Core Widget: `CustomerPortal`
+
+Displays a customizable customer dashboard with plans, subscriptions, billing, credits, and more.
+
+```tsx
+import { CustomerPortal } from "@metrifox/react-sdk"
+
+const MyCustomPlan = ({ foo }) => <div>Custom Plan! Foo: {foo}</div>
+
+export default function MyPortalPage() {
+  return (
+    <CustomerPortal
+      customerKey="your-customer-key"
+      sectionsConfig={[
+        { key: "subscription" },
+        { key: "plan", component: MyCustomPlan, props: { foo: "bar" } },
+        { key: "billingHistory", hidden: true },
+      ]}
+    />
+  )
+}
+```
+
+---
+
+## Section Configuration
+
+The `sectionsConfig` prop controls what appears in the portal.
+
+| Property    | Type                      | Description                                         |
+| ----------- | ------------------------- | --------------------------------------------------- |
+| `key`       | `SectionKey`              | Unique key of the section (see list below)          |
+| `hidden`    | `boolean`                 | Hide this section when `true`                       |
+| `component` | `React.ComponentType`     | Replace the default section with your own component |
+| `props`     | `Record<string, unknown>` | Extra props passed to the custom or default section |
+
+### Built-in Section Keys
+
+| Key                | Description                   |
+| ------------------ | ----------------------------- |
+| `upcomingInvoice`  | Displays next invoice details |
+| `subscription`     | Active subscription overview  |
+| `walletBalance`    | Shows user wallet balance     |
+| `entitlementUsage` | Displays resource usage       |
+| `paymentOverview`  | Payment summary and methods   |
+| `billingHistory`   | List of past transactions     |
+| `plan`             | Current plan details          |
+
+### Section Anchors
+
+Each portal section now renders inside a `<section id="...">` wrapper so you can link directly to segments of a customer portal view. The default anchor IDs are:
+
+| Anchor ID          | Section Key        |
+| ------------------ | ------------------ |
+| `#upcoming-invoice` | `upcomingInvoice` |
+| `#subscription`     | `subscription`    |
+| `#credit-balance`   | `creditBalance`   |
+| `#entitlement-usage`| `entitlementUsage`|
+| `#payment-overview` | `paymentOverview` |
+| `#billing-history`  | `billingHistory`  |
+| `#plan`             | `plan`            |
+
+Use these anchors when embedding the SDK or sharing deep links (e.g., `https://app.example.com/portal#billing-history`).
+
+---
+
+## Styling
+
+Import the SDK’s global styles into your app entry (e.g., `src/index.tsx` or `_app.tsx`):
+
+```tsx
+import "@metrifox/react-sdk/dist/styles.css"
+```
+
+> This is required for proper styling of all widgets.
+
+---
+
+## Local Development
+
+### Using [yalc](https://github.com/wclr/yalc)
+
+For local SDK testing:
+
+```bash
+# In SDK project
+pnpm build
+npx yalc publish
+
+# In consuming app
+npx yalc add @metrifox/react-sdk
+pnpm install
+```
+
+#### Auto-update during development
+
+```bash
+# In SDK project
+pnpm dev:build   # watch & rebuild
+pnpm dev:link    # re-publish build to yalc
+
+# In consuming project
+npx yalc update @metrifox/react-sdk
+```
+
+#### Clean up
+
+```bash
+npx yalc remove @metrifox/react-sdk
+pnpm install
+```
+
+---
+
+## Support
+
+📘 **Full Documentation:**
+For detailed guides, API references, and live examples, visit [docs.metrifox.com](https://docs.metrifox.com).
+
+---
+
+## 📄 License
+
+MIT © [MetriFox](https://metrifox.com)