@crimson-education/replit-sdk 1.0.2-beta-15 → 1.0.2-beta-16

package/Readme.md

@@ -1,75 +1,107 @@
-## Replit SDK for Crimson App
+# Replit SDK for Crimson App
 
 This SDK facilitates the rapid integration of Replit-hosted applications into the Crimson ecosystem.
 
-### Core Principle
+## Core Principle
 
-The integration functions by passing environment variables and user parameters via URL parameters to the Replit frontend. This data is stored in-memory and persists until the current session ends.
+The integration works by passing environment variables and user parameters via URL parameters (query string or hash) to the Replit frontend. This data is stored in-memory and persists until the current session ends, providing a seamless iframe integration experience.
 
-Project Structure
+## Project Structure
 
-- api
+- **`api`**:
+  - `bindApi(app)`: Binds `/api/function` routes to an Express app for forwarding GraphQL requests.
+  - `graphqlProxySchema`: Zod schema for the proxy request body.
+- **`components`**:
+  - `ExternalLink`: A specialized component designed to handle navigation to external URLs (out of iframe).
+- **`hooks`**:
+  - `useUrlParams()`: Extracts and stores essential data (Auth Tokens, API endpoints) from the URL.
+  - `getStoredParam(key)` / `setStoredParams(values)`: Utilities for managing persisted parameters.
+- **`functions`**:
+  - Implementations for fundamental Crimson API calls like `fetchLoginUser` and `fetchMyStudents`.
+- **`utils`**:
+  - `initDatadog(config)`: Manages Datadog initialization.
+  - `trackEvent(name)`: Analytics utility.
+  - `apiRequest(query, variables)`: A pre-configured GraphQL request client wrapper.
 
-  (expressRouter.ts): Provides the bindApi function, used to bind /api/function routes to server.js for forwarding API request calls.
+## Quick Integration Guide
 
-  (graphqlProxy.ts): Defines the data structures and schemas used for forwarding GraphQL interface requests.
+To integrate your Replit app into the Crimson ecosystem, follow these steps:
 
-- components
+### 1. Install the SDK
 
-  (external-link.tsx): A specialized component designed to handle navigation to external URLs.
+```bash
+npm install @crimson-education/replit-sdk@1.0.2-beta-15
+```
 
-- hooks
+### 2. Wrap your App with DevProvider
 
-  (use-url-params.ts): The core hook for processing parameters passed via iframe. It extracts essential data such as Auth Tokens and Environment API endpoints.
+Initialize the context at the top level of your application.
 
-- functions
+```tsx
+import { IDevProvider } from '@crimson-education/replit-sdk/lib/context/dev-context';
 
-  (index.ts): Contains implementations for fundamental API calls, including: `fetchLoginUser`, `getMyStudents`
+function App() {
+  return (
+    <IDevProvider>
+      <YourAppRoutes />
+    </IDevProvider>
+  );
+}
+```
 
-- utils
+### 3. Setup Express Proxy
 
-  (datadog.ts): Manages the Datadog initialization instance and provides the trackEvent function for analytics.
+In your server-side code (e.g., `server/routes.ts`), bind the API proxy:
 
-  (event.ts): Utilities for iframe-to-parent communication using the postMessage API.
+```typescript
+import { bindApi } from '@crimson-education/replit-sdk';
 
-  (queryClient.ts): A pre-configured API request client wrapper.
+export function registerRoutes(app: Express) {
+  bindApi(app);
+  // ... other routes
+}
+```
 
-### Here is a set of prompts that you may need
+### 4. Use URL Parameters Hook
 
-Prompts from replit:
+In your main component, use the hook to sync URL parameters to memory:
 
-````
- we are going to embed the app on a iframe, so now you need to do all things one by one listed here:
-1. install and save package @crimson-education/replit-sdk@1.0.2-beta-14
-2. wrap the App with the `IDevProvider` context, like
-  ```
-  // ...
-  import { IDevProvider } from "@crimson-education/replit-sdk/lib/context/dev-context";
-  // ...
-  function App() {
-    return (
-      <IDevProvider>
-        <QueryClientProvider client={queryClient}>
-          <TooltipProvider>
-            <Toaster />
-            <Router />
-          </TooltipProvider>
-        </QueryClientProvider>
-      </IDevProvider>
-    );
-  }
-  ```
-3. set Express proxy endpint, call `bindApi(app)` to bind `/api/function` route in `server/routes.ts`
-4. use the ExternalLink component to replace all the <a> tag which has a external link.
-5. set dev capp endpoint on top of the app before any api call like ```
-import { setStoredParams } from "@crimson-education/replit-sdk/lib/hooks/use-url-params";
-setStoredParams({'cappEndpoint': 'http://6d94f1eb.r8.cpolar.top/graphql'});```
-6. remove fetch button and staff userId input in every student picker dialog, and set getStoredUserId() as default staffId to load students once the dialog opened.
-7. replace the fetchLoginUser and fetchMyStudent function, use the exported functions from the sdk and clean up the redundant server-side endpoints.
-8. the fetchStudents api could return duplicated students, remove them to keep unique
-9. init datadog, like: ```import { init as datadogInit } from "@crimson-education/replit-sdk/lib/utils/datadog";
-datadogInit({ app: '{{here is the replit app name}}' });```
-10. use trackEvent function to track all events that you may intrest, ```import { ExternalLink, trackEvent } from "@crimson-education/replit-sdk";
-trackEvent('OPEN_COPILOT'); ```
+```tsx
+import { useUrlParams } from '@crimson-education/replit-sdk/lib/hooks/use-url-params';
 
-````
+function MainComponent() {
+  useUrlParams();
+  return <div>My Content</div>;
+}
+```
+
+### 5. Handle External Links
+
+Use the `ExternalLink` component for any links that should open outside the iframe:
+
+```tsx
+import { ExternalLink } from '@crimson-education/replit-sdk';
+
+<ExternalLink href="https://app.crimsoneducation.org">Go to Crimson App</ExternalLink>;
+```
+
+### 6. Initialize Analytics (Optional)
+
+```typescript
+import { init as datadogInit, trackEvent } from '@crimson-education/replit-sdk';
+
+datadogInit({ app: 'your-replit-app-name' });
+trackEvent('APP_LAUNCHED');
+```
+
+### 7. Fetch Crimson Data
+
+Use the built-in functions to fetch user or student data:
+
+```typescript
+import { fetchLoginUser, fetchMyStudents } from '@crimson-education/replit-sdk/lib/functions';
+
+const user = await fetchLoginUser();
+// you may get multiple roles, just keep one of 'STRATEGIST', 'CASE_MANAGER', 'TUTOR',
+const students = await fetchMyStudents(user.userId, ['STRATEGIST']);
+```

package/lib/components/external-link.js

@@ -8,7 +8,7 @@ const react_1 = __importDefault(require("react"));
 const use_url_params_1 = require("../hooks/use-url-params");
 const datadog_1 = require("../utils/datadog");
 function ExternalLink({ href, replit, children, eventName = 'external_link_click', onClick, ...props }) {
-    const isReplit = replit !== null && replit !== void 0 ? replit : (href.endsWith('replit.app') || href.includes('replit.com/t'));
+    const isReplit = replit !== null && replit !== void 0 ? replit : (href.includes('replit.app') || href.includes('replit.com/t'));
     const parentDomain = (0, use_url_params_1.getStoredParam)('parentDomain') || '';
     const finalHref = isReplit && parentDomain ? parentDomain + '/replit/t?redirect=' + encodeURIComponent(href) : href;
     const handleClick = (event) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crimson-education/replit-sdk",
-  "version": "1.0.2-beta-15",
+  "version": "1.0.2-beta-16",
   "description": "SDK for Replit app integration",
   "publishConfig": {
     "access": "public"