@refoldai/refold-js 10.0.0

package/.claude/skills/method/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: method
+description: Add a new public API method to the Refold SDK with types, JSDoc, and endpoint mapping. Use when adding new SDK functionality.
+metadata:
+  author: iamtraction
+  version: "1.0.0"
+  argument-hint: <method-name>
+---
+
+# Add SDK Method
+
+Add a new public API method to the Refold class with TypeScript types, JSDoc documentation, and backend endpoint mapping.
+
+## Usage
+
+The user provides a method name (e.g., "getWorkflows", "createConfig") and describes the backend endpoint it maps to.
+
+## Steps
+
+1. **Ask for details** if not provided: method name, HTTP method, endpoint URL, request payload shape, response shape, whether it supports pagination
+2. **Define TypeScript interfaces** — request payload and response types
+3. **Add JSDoc-documented method** to the `Refold` class
+4. **Build** to verify compilation
+
+## Implementation Order
+
+1. **Interfaces** — Define request/response types (before the class)
+2. **Method** — Add to `Refold` class with JSDoc
+3. **Build** — Run `npm run build` to generate `.js` and `.d.ts`
+
+## Interface Template
+
+```ts
+// Add before the Refold class in refold.ts
+
+/** The payload for creating a resource. */
+export interface CreateResourcePayload {
+    /** The resource name. */
+    name: string;
+    /** Optional description. */
+    description?: string;
+    /** Configuration object. */
+    config?: Record<string, unknown>;
+}
+
+/** A resource object. */
+export interface Resource {
+    /** The resource ID. */
+    _id: string;
+    /** The resource name. */
+    name: string;
+    /** The resource description. */
+    description?: string;
+    /** When the resource was created. */
+    createdAt: string;
+    /** When the resource was last updated. */
+    updatedAt: string;
+}
+```
+
+## Method Templates
+
+### GET Request (single item)
+
+```ts
+/**
+ * Returns the resource details for the specified resource ID.
+ * @param {String} id The resource ID.
+ * @returns {Promise<Resource>} The resource details.
+ */
+public async getResource(id: string): Promise<Resource> {
+    const res = await fetch(`${this.baseUrl}/api/v2/f-sdk/resource/${id}`, {
+        headers: {
+            authorization: `Bearer ${this.token}`,
+        },
+    });
+
+    if (res.status >= 400 && res.status < 600) {
+        const error = await res.json();
+        throw error;
+    }
+
+    return await res.json();
+}
+```
+
+### GET Request (list with optional overloads)
+
+```ts
+/**
+ * Returns the list of all resources.
+ * @returns {Promise<Resource[]>} The list of resources.
+ */
+public async getResources(): Promise<Resource[]>;
+/**
+ * Returns the resource details for the specified slug.
+ * @param {String} slug The resource slug.
+ * @returns {Promise<Resource>} The resource details.
+ */
+public async getResources(slug: string): Promise<Resource>;
+public async getResources(slug?: string): Promise<Resource | Resource[]> {
+    const res = await fetch(`${this.baseUrl}/api/v2/f-sdk/resource${slug ? `/${slug}` : ""}`, {
+        headers: {
+            authorization: `Bearer ${this.token}`,
+        },
+    });
+
+    if (res.status >= 400 && res.status < 600) {
+        const error = await res.json();
+        throw error;
+    }
+
+    return await res.json();
+}
+```
+
+### POST Request (with JSON body)
+
+```ts
+/**
+ * Creates a new resource with the specified configuration.
+ * @param {CreateResourcePayload} payload The resource configuration.
+ * @returns {Promise<Resource>} The created resource.
+ */
+public async createResource(payload: CreateResourcePayload): Promise<Resource> {
+    const res = await fetch(`${this.baseUrl}/api/v2/f-sdk/resource`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${this.token}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+
+    if (res.status >= 400 && res.status < 600) {
+        const error = await res.json();
+        throw error;
+    }
+
+    return await res.json();
+}
+```
+
+### PUT Request (update)
+
+```ts
+/**
+ * Updates an existing resource.
+ * @param {String} id The resource ID.
+ * @param {Partial<CreateResourcePayload>} payload The fields to update.
+ * @returns {Promise<Resource>} The updated resource.
+ */
+public async updateResource(id: string, payload: Partial<CreateResourcePayload>): Promise<Resource> {
+    const res = await fetch(`${this.baseUrl}/api/v2/f-sdk/resource/${id}`, {
+        method: "PUT",
+        headers: {
+            authorization: `Bearer ${this.token}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+
+    if (res.status >= 400 && res.status < 600) {
+        const error = await res.json();
+        throw error;
+    }
+
+    return await res.json();
+}
+```
+
+### DELETE Request
+
+```ts
+/**
+ * Deletes the specified resource.
+ * @param {String} id The resource ID.
+ * @returns {Promise<unknown>} The deletion result.
+ */
+public async deleteResource(id: string): Promise<unknown> {
+    const res = await fetch(`${this.baseUrl}/api/v2/f-sdk/resource/${id}`, {
+        method: "DELETE",
+        headers: {
+            authorization: `Bearer ${this.token}`,
+        },
+    });
+
+    if (res.status >= 400 && res.status < 600) {
+        const error = await res.json();
+        throw error;
+    }
+
+    return await res.json();
+}
+```
+
+### Paginated GET Request
+
+```ts
+/**
+ * Returns a paginated list of resources.
+ * @param {Object} [params] Pagination parameters.
+ * @param {Number} [params.page] The page number.
+ * @param {Number} [params.limit] The number of items per page.
+ * @returns {Promise<PaginatedResponse<Resource>>} The paginated list.
+ */
+public async listResources(params?: { page?: number; limit?: number }): Promise<PaginatedResponse<Resource>> {
+    const query = new URLSearchParams();
+    if (params?.page) query.set("page", String(params.page));
+    if (params?.limit) query.set("limit", String(params.limit));
+
+    const res = await fetch(`${this.baseUrl}/api/v2/f-sdk/resources?${query}`, {
+        headers: {
+            authorization: `Bearer ${this.token}`,
+        },
+    });
+
+    if (res.status >= 400 && res.status < 600) {
+        const error = await res.json();
+        throw error;
+    }
+
+    return await res.json();
+}
+```
+
+## Existing Patterns Reference
+
+### Error Handling Pattern (used by ALL methods)
+```ts
+if (res.status >= 400 && res.status < 600) {
+    const error = await res.json();
+    throw error;
+}
+```
+
+### Auth Header (used by ALL methods)
+```ts
+headers: {
+    authorization: `Bearer ${this.token}`,
+}
+```
+
+### Custom Headers (some methods pass app slug)
+```ts
+headers: {
+    authorization: `Bearer ${this.token}`,
+    "content-type": "application/json",
+    slug,  // Custom header for app context
+}
+```
+
+### PaginatedResponse Generic
+```ts
+interface PaginatedResponse<T> {
+    docs: T[];
+    totalDocs: number;
+    limit: number;
+    totalPages: number;
+    page: number;
+}
+```
+
+## Verification
+
+```bash
+npm run build     # Compile to refold.js + refold.d.ts
+npm run docs:llms # Generate TypeDoc (optional)
+```
+
+## Important
+
+- **Zero dependencies** — only use native `fetch`, no external HTTP libraries
+- **JSDoc on every method** — TypeDoc generates SDK documentation from these
+- **JSDoc on every interface field** — include description for each property
+- **Method overloads** — use TypeScript overloads for methods with optional parameters that change return type
+- **Error handling** — always check `res.status >= 400 && res.status < 600` and throw the parsed error
+- **`Bearer` auth** — all methods include `authorization: Bearer ${this.token}`
+- **Single file** — everything goes in `refold.ts`, no separate files
+- **Export interfaces** — all types are exported for consumer use
+- **Backward compatibility** — never rename or remove existing methods, use `@deprecated` JSDoc tag
+- **Build output** — `refold.js` (CommonJS) + `refold.d.ts` (type declarations)

package/.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: review-pr
+description: Review a pull request for code quality, patterns consistency, and potential issues. Use when asked to review a PR by number or URL.
+metadata:
+  author: iamtraction
+  version: "1.0.0"
+  argument-hint: <pr-number-or-url>
+---
+
+# Review Pull Request
+
+Perform a thorough code review of a GitHub pull request.
+
+## Usage
+
+The user provides a PR number or URL (e.g., `123`, `https://github.com/gocobalt/refold-js/pull/123`).
+
+## Steps
+
+1. **Fetch PR details** using `gh pr view {number} --json title,body,files,additions,deletions,baseRefName,headRefName`
+2. **Fetch the diff** using `gh pr diff {number}`
+3. **Analyze every changed file** against the checklist below
+4. **Output a structured review** with findings grouped by severity
+
+## Review Checklist
+
+### SDK Design
+- Zero runtime dependencies maintained — no new `dependencies` added to package.json
+- Public API backward compatible — no breaking changes without major version bump
+- Deprecated methods/fields marked with `@deprecated` JSDoc, not removed
+- New public methods have JSDoc with `@param` and `@returns`
+- New interfaces/types exported correctly
+- Error handling follows existing pattern: throw parsed JSON for 4xx/5xx responses
+- Native `fetch` API used — no axios, node-fetch, or other HTTP libraries
+- OAuth popup flow: no changes that break `window.open()` + polling pattern
+
+### Code Quality
+- TypeScript strict mode passes — no `any` types unless truly unavoidable
+- All public methods have explicit return types
+- No unused imports or dead code
+- No hardcoded URLs — base URL comes from constructor option
+- Bearer token attached to all requests via `Authorization` header
+- Pagination support: `page`/`limit` parameters where applicable
+
+### Backward Compatibility
+- Existing method signatures unchanged (or new optional params added at the end)
+- Existing interfaces only extended, never fields removed
+- `connected` and `auth_type` fields preserved (deprecated, not removed)
+- AuthType enum values unchanged
+
+### Security
+- No secrets or tokens in code
+- No `eval()`, `Function()`, or dynamic code execution
+- Token not logged or exposed in error messages
+
+### Naming & Style
+- 4 spaces indentation, double quotes, semicolons
+- camelCase for methods/variables, PascalCase for interfaces/types/enums
+- Method names follow existing patterns: `get*`, `create*`, `update*`, `delete*`, `execute*`
+
+## Output Format
+
+```
+## PR Review: #{number} — {title}
+
+### Summary
+Brief description of what the PR does.
+
+### Critical Issues
+- **[file:line]** Description of critical issue
+
+### Suggestions
+- **[file:line]** Description of improvement suggestion
+
+### Nits
+- **[file:line]** Minor style/preference issue
+
+### Positive Notes
+- Things done well worth calling out
+```

package/.claude/skills/style/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: style
+description: Code style and formatting conventions for this codebase. Reference this when writing or reviewing code to ensure consistency.
+metadata:
+  author: iamtraction
+  version: "1.0.0"
+  user-invocable: false
+---
+
+# Code Style Guide
+
+These conventions apply to all code written in this codebase. Follow them when creating, modifying, or reviewing code.
+
+## Formatting
+
+- **Indentation:** 4 spaces — never tabs
+- **Quotes:** Double quotes for strings
+- **Semicolons:** Always
+- **Line endings:** Unix (LF)
+- **Trailing commas:** Use trailing commas in multiline arrays, objects, function parameters, and imports
+- **Blank lines:** One blank line between top-level declarations (imports, interfaces, functions, exports). No multiple consecutive blank lines.
+- **Braces:** Opening brace on the same line (`if (...) {`), closing brace on its own line
+- **Bracket spacing:** Spaces inside object braces — `{ key: value }`, not `{key: value}`
+- **Template literals:** Prefer template literals over string concatenation
+
+## Naming
+
+- **Functions/variables:** camelCase — `getApp`, `executeWorkflow`, `configId`
+- **Constants:** SCREAMING_SNAKE_CASE for true constants
+- **Interfaces/Types:** PascalCase, no `I` prefix — `Application`, `Config`, `Execution`
+- **Enums:** PascalCase name, PascalCase members — `AuthType.OAuth2`, `AuthStatus.Active`
+- **Booleans:** Prefix with `is`, `has`, `can`, `should` — `isConnected`, `hasToken`
+
+## TypeScript
+
+- **Strict typing:** Avoid `any` — use `unknown` when the type is genuinely unknown, then narrow
+- **Interfaces over types:** Prefer `interface` for object shapes, `type` for unions, intersections, and utility types
+- **Explicit return types:** Add them for all public methods — this is a published SDK, types are the API contract
+- **Non-null assertions:** Avoid `!` — prefer optional chaining (`?.`) and nullish coalescing (`??`)
+
+## SDK-Specific Conventions
+
+- **Zero dependencies:** This SDK has no runtime dependencies. Do not add any. Use native `fetch` API.
+- **Single class:** All public API lives on the `Refold` class. Keep it that way.
+- **Backward compatibility:** Mark deprecated fields/methods with `@deprecated` JSDoc tag — never remove them without a major version bump
+- **Error propagation:** Throw parsed JSON error responses for 4xx/5xx — don't catch and transform in the SDK. Let consumers handle errors.
+- **JSDoc on all public methods:** Every public method must have a JSDoc block with `@param` and `@returns` tags. This generates the TypeDoc documentation.
+
+## Functions
+
+- **Method style:** Use class methods for the `Refold` class
+- **Private methods:** Mark with `private` keyword — `private oauth(...)`, `private keybased(...)`
+- **Async/await:** All API calls are async — use `async`/`await`, never raw `.then()` chains in new code
+- **Early returns:** Prefer early returns to reduce nesting
+
+## Error Handling
+
+- **Fetch errors:** Check `res.status >= 400 && res.status < 600`, parse JSON, throw it
+- **No try/catch in SDK methods** — let errors propagate to the consumer
+- **OAuth polling:** Catch errors in the polling interval and log to console — don't reject the promise on transient failures
+
+## Comments
+
+- **JSDoc for all public API** — every exported method, interface, enum, and type
+- **No obvious comments** — don't describe what the code does when it's self-evident
+- **Why, not what** — comment the reasoning, not the mechanics
+- **No commented-out code** — delete it; git has history

package/.claude/skills/verify/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: verify
+description: Verify code quality, catch bugs, and validate implementation against codebase patterns. Use for testing, linting, type-checking, and manual review.
+metadata:
+  author: iamtraction
+  version: "1.0.0"
+  argument-hint: <file-path-or-feature>
+---
+
+# Verify & Test
+
+Perform comprehensive verification of code changes.
+
+## Usage
+
+The user provides a file path, feature name, or asks to verify recent changes. If no argument, verify all uncommitted changes.
+
+## Verification Steps
+
+### 1. Static Analysis
+Run these checks and report results:
+```bash
+npm run build         # TypeScript compilation → refold.js + refold.d.ts
+```
+
+### 2. Type Safety Review
+- Check for `any` types that should be properly typed
+- Verify all public methods have explicit return types
+- Ensure interface fields match the backend API responses
+- Verify generic type parameters on Promise return types
+- Check that deprecated fields are still present with `@deprecated` JSDoc
+
+### 3. SDK Design Compliance
+Verify the code follows SDK conventions:
+- **Zero dependencies**: No runtime dependencies added
+- **Native fetch**: No HTTP libraries — uses `fetch` API only
+- **Single class**: All public API on the `Refold` class
+- **Error handling**: 4xx/5xx → parse JSON → throw (no swallowing errors)
+- **JSDoc on all public methods**: `@param`, `@returns` tags
+- **Backward compatibility**: No removed methods/fields, no changed signatures
+
+### 4. Runtime Safety Review
+Check for common issues:
+- **Missing error checks** — `res.status >= 400` not checked after fetch
+- **OAuth polling** — `setInterval` properly cleaned up with `clearInterval`
+- **Popup handling** — `window.open` result checked for null (popup blocked)
+- **Token usage** — `this.token` attached to all requests
+- **Base URL** — uses `this.baseUrl`, no hardcoded URLs
+
+### 5. Backward Compatibility Check
+- Existing method signatures unchanged
+- Existing interfaces only extended (no field removal)
+- Enum values unchanged
+- `getApp()` overload still works for both single and all apps
+
+## Output Format
+
+```
+## Verification Report
+
+### Build: PASS/FAIL
+Details...
+
+### Type Safety: X issues found
+- [file:line] Description
+
+### SDK Design: X issues found
+- [file:line] Description
+
+### Runtime Safety: X issues found
+- [file:line] Description
+
+### Backward Compatibility: X issues found
+- [file:line] Description
+
+### Overall: PASS / NEEDS FIXES
+Summary and recommended actions.
+```
+
+## Important
+
+- Always run `npm run build` — don't skip compilation check
+- Verify both `refold.js` and `refold.d.ts` are generated correctly
+- Be specific about issues — include file paths and line numbers
+- Breaking changes require major version bump — flag them as critical

package/.github/pull_request_template.md

@@ -0,0 +1,48 @@
+<!--
+Paste your Linear ticket ID anywhere in this PR.
+Valid formats: DEV-123, closes DEV-123, resolves DEV-456, fixes AIA-789
+-->
+DEV-
+
+### Summary
+<!-- Required. What does this PR do and why? Be specific — mention what changed and the reason for the change. -->
+
+### Approach
+<!--
+Optional — include for new features or large changes.
+- What approach did you take and why?
+- What alternatives did you consider and why were they rejected?
+-->
+
+### Test Plan
+<!--
+Required. Steps for testing these changes — what to do and what to verify.
+At least one checkbox is required.
+-->
+
+- [ ]
+
+### Claude Code
+<!--
+If this PR was built with Claude Code, check all that apply.
+Delete this section entirely for PRs not written with Claude Code.
+-->
+
+- [ ] Used `superpowers:brainstorming` before starting implementation
+- [ ] Plan file added to `docs/superpowers/plans/`
+
+### Env Changes
+<!--
+Include ONLY if this PR adds, removes, or modifies environment variables.
+Delete this section entirely if there are no env var changes.
+
+Format:
+  - name: VAR_NAME
+    action: add | remove | update
+    type: configmap | secret
+    value: "example_value"          # omit for secrets
+    description: What this var does and where it's used
+-->
+
+```yaml
+```

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,35 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+      - run: |
+          echo 'NPM Token ${secrets.NPM_TOKEN}'
+          npm ci
+          npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}