@nexical/sdk-core 0.1.0 → 0.1.1

package/.skills/sdk-core-client-foundation/SKILL.md

@@ -0,0 +1,78 @@
+# Skill: SDK Core Client Foundation
+
+This skill governs the implementation and extension of the core SDK infrastructure within the Nexical Ecosystem. It defines the foundational `ApiClient`, error handling mechanisms, and authentication strategies that power all module-specific SDKs.
+
+## 1. Core Principles
+
+### Named Export Infrastructure
+
+Core SDK infrastructure components (interfaces, classes, errors) MUST use named exports. This ensures explicit importing, better IDE support, and efficient tree-shaking.
+
+- **Rule**: Default exports are strictly forbidden in the `sdk-core` package.
+
+### Strict Type Safety (No `any`)
+
+In accordance with `CODE.md`, the `any` type is strictly forbidden.
+
+- **Rule**: Use `unknown` for dynamic request bodies and error data. Use concrete interfaces or properly constrained generics for all other structures.
+
+### ESM Compliance
+
+- **Rule**: All relative imports MUST include the `.js` extension to satisfy ESM runtime requirements.
+
+---
+
+## 2. Architectural Patterns
+
+### Asynchronous Auth Strategy
+
+Authentication logic is decoupled from the `ApiClient` via the `AuthStrategy` interface. This allows for polymorphic authentication (Bearer tokens, API Keys, or Agent-based auth).
+
+- **Implementation**: The `ApiClient` calls `authStrategy.getHeaders()` dynamically for every request.
+- **Pattern**: `export interface AuthStrategy { getHeaders(): Promise<Record<string, string>>; }`
+
+### Structured Error Handling (`NexicalError`)
+
+All API errors MUST be wrapped in the `NexicalError` class. This class is responsible for extracting error messages from various JSON structures (e.g., `error`, `message`) and preserving the HTTP status context.
+
+- **Pattern**: `throw new NexicalError(response.status, response.statusText, errorData);`
+
+### Generic Request Orchestration
+
+All API requests MUST use the generic `request<T>` method provided by the `ApiClient`. This method handles boilerplate such as:
+
+- Base URL normalization.
+- Header merging (including dynamic auth headers).
+- JSON stringification for bodies.
+- Environment-aware credential inclusion (defaulting to `include`).
+- **Rule**: Direct use of the global `fetch` is forbidden within the SDK layer.
+
+---
+
+## 3. Operational "Gotchas"
+
+### 204 No Content Compatibility
+
+Requests returning a `204 No Content` status MUST return an empty object (`{}`) cast to the expected generic type `T`. This prevents "Unexpected end of JSON input" errors during parsing.
+
+- **Pattern**: `if (response.status === 204) { return {} as T; }`
+
+### Base URL Normalization
+
+The `ApiClient` constructor MUST normalize the `baseUrl` to remove any trailing slashes. This prevents double-slashes or malformed paths during path concatenation.
+
+- **Pattern**: `this.baseUrl = options.baseUrl.replace(/\/$/, '');`
+
+### Default Credential Inclusion
+
+The client defaults to `include` for credentials to ensure cookies/auth headers are sent by default in browser environments.
+
+- **Rule**: The `ApiClient` MUST default to `include` for credentials unless explicitly overridden in `RequestInit`.
+
+---
+
+## 4. Centralized SDK Integration
+
+The core foundation supports the **Centralized SDK Mandate** defined in `ARCHITECTURE.md`. All module-specific SDKs are aggregated into a global `api` object.
+
+- **Requirement**: Use the `ApiClient` as the engine for all module SDK resources.

package/.skills/sdk-core-client-foundation/examples/usage.ts

@@ -0,0 +1,62 @@
+/**
+ * @docker/Dockerfile example-usage.ts
+ * @description Example demonstrating the implementation of the SDK Core patterns.
+ */
+
+import { ApiClient } from './client.js';
+import type { AuthStrategy } from './auth.js';
+import { NexicalError } from './errors.js';
+
+/**
+ * Example of a Bearer Token Auth Strategy.
+ */
+class BearerAuthStrategy implements AuthStrategy {
+  constructor(private readonly token: string) {}
+
+  async getHeaders(): Promise<Record<string, string>> {
+    return {
+      Authorization: `Bearer ${this.token}`,
+    };
+  }
+}
+
+/**
+ * Example of consuming the ApiClient in a Resource class.
+ */
+class UserResource {
+  constructor(private readonly client: ApiClient) {}
+
+  async getProfile(userId: string): Promise<unknown> {
+    try {
+      // Pattern: Generic Request Orchestration
+      return await this.client.request<unknown>('GET', `/users/${userId}`);
+    } catch (error) {
+      if (error instanceof NexicalError) {
+        // Pattern: Structured Error Handling
+        console.error(`API Error (${error.status}): ${error.message}`);
+        throw error;
+      }
+      throw error;
+    }
+  }
+
+  async deleteUser(userId: string): Promise<void> {
+    // Pattern: 204 No Content Compatibility
+    // The request method returns {} for 204, satisfying the generic T (here void-ish)
+    await this.client.request<void>('DELETE', `/users/${userId}`);
+  }
+}
+
+// Initialization
+const auth = new BearerAuthStrategy('my-secret-token');
+const client = new ApiClient({
+  baseUrl: 'https://api.nexical.com/', // Pattern: Base URL Normalization handles the slash
+  authStrategy: auth,
+});
+
+const userResource = new UserResource(client);
+
+// Demonstrate usage to satisfy linting
+userResource.getProfile('current-user').catch(() => {
+  /* Handle or ignore for example purposes */
+});

package/.skills/sdk-core-client-foundation/templates/auth-strategy.tsf

@@ -0,0 +1,16 @@
+/**
+ * @docker/Dockerfile auth-strategy.tsf
+ * @description Interface definition for AuthStrategy.
+ */
+
+/**
+ * Pattern: Asynchronous Auth Strategy
+ * Allows for polymorphic authentication resolved dynamically.
+ */
+export interface AuthStrategy {
+  /**
+   * Resolves the headers required for authentication.
+   * @returns A promise resolving to a record of header keys and values.
+   */
+  getHeaders(): Promise<Record<string, string>>;
+}

package/.skills/sdk-core-client-foundation/templates/client-base.tsf

@@ -0,0 +1,90 @@
+/**
+ * @docker/Dockerfile client-base.tsf
+ * @description Fragment for the base ApiClient class.
+ */
+
+import type { AuthStrategy } from './auth.js';
+import { NexicalError } from './errors.js';
+
+export interface ApiClientOptions {
+  baseUrl: string;
+  authStrategy: AuthStrategy;
+}
+
+/**
+ * Pattern: Named Export Infrastructure
+ * The core ApiClient uses named exports and handles request orchestration.
+ */
+export class ApiClient {
+  private readonly baseUrl: string;
+  private readonly authStrategy: AuthStrategy;
+
+  constructor(options: ApiClientOptions) {
+    /** 
+     * Pattern: Base URL Normalization
+     * Normalizes the baseUrl to remove trailing slashes.
+     */
+    this.baseUrl = options.baseUrl.replace(/\/$/, '');
+    this.authStrategy = options.authStrategy;
+  }
+
+  /**
+   * Pattern: Generic Request Orchestration
+   * Orchestrates the API request lifecycle with full type safety.
+   */
+  async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+    options: RequestInit = {}
+  ): Promise<T> {
+    const authHeaders = await this.authStrategy.getHeaders();
+    const url = `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+
+    const config: RequestInit = {
+      ...options,
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...authHeaders,
+        ...options.headers,
+      },
+      /**
+       * Pattern: Default Credential Inclusion
+       * Default to 'include' for cookies/auth headers in browser environments.
+       */
+      credentials: options.credentials || 'include',
+    };
+
+    if (body) {
+      config.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, config);
+
+    /**
+     * Pattern: 204 No Content Compatibility
+     * Return an empty object to prevent JSON parsing errors.
+     */
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    if (!response.ok) {
+      let errorData: unknown;
+      try {
+        errorData = await response.json();
+      } catch {
+        errorData = { message: response.statusText };
+      }
+
+      /**
+       * Pattern: Structured Error Handling
+       * Wraps API errors in the NexicalError class.
+       */
+      throw new NexicalError(response.status, response.statusText, errorData);
+    }
+
+    return response.json() as Promise<T>;
+  }
+}

package/.skills/sdk-core-client-foundation/templates/error-handler.tsf

@@ -0,0 +1,45 @@
+/**
+ * @docker/Dockerfile error-handler.tsf
+ * @description The NexicalError implementation pattern.
+ */
+
+/**
+ * Pattern: Structured Error Handling (NexicalError)
+ * Standardized error wrapper that extracts messages from various JSON structures.
+ */
+export class NexicalError extends Error {
+  public readonly status: number;
+  public readonly statusText: string;
+  public readonly data: unknown;
+
+  constructor(status: number, statusText: string, data: unknown) {
+    const message = NexicalError.extractMessage(data) || statusText || 'API Error';
+    super(message);
+    this.status = status;
+    this.statusText = statusText;
+    this.data = data;
+    this.name = 'NexicalError';
+  }
+
+  /**
+   * Extract an error message from a dynamic JSON response body.
+   * @param data - The error payload (using unknown to avoid 'any').
+   * @returns A string error message if found, otherwise undefined.
+   */
+  private static extractMessage(data: unknown): string | undefined {
+    if (typeof data === 'string') {
+      return data;
+    }
+
+    if (data && typeof data === 'object') {
+      const payload = data as Record<string, unknown>;
+      return (
+        (payload.error as string) ||
+        (payload.message as string) ||
+        (payload.msg as string)
+      );
+    }
+
+    return undefined;
+  }
+}

package/.skills/sdk-core-esm-imports/SKILL.md

@@ -0,0 +1,51 @@
+# Skill: SDK ESM Imports & Resource Standards
+
+This skill enforces strict ESM compatibility and architectural consistency within the `sdk-core` package.
+
+## Context
+
+The `sdk-core` package provides the foundational primitives for the Nexical SDK. It must strictly adhere to ESM runtime requirements (specifically explicit file extensions) and follow the Abstract Resource pattern for consistent request orchestration.
+
+## Standards
+
+### 1. Strict ESM Relative Imports
+
+All relative imports MUST include the explicit `.js` extension. This is required for Node.js ESM resolution and compatibility across the ecosystem.
+
+- **Rule**: Relative imports MUST end in `.js`.
+- **Example**: `import { ApiClient } from './client.js';`
+
+### 2. Abstract SDK Resource Pattern
+
+SDK functional areas are organized into 'Resource' classes that extend `BaseResource`.
+
+- **Rule**: Every SDK resource MUST extend `BaseResource`.
+- **Rule**: Resources MUST receive an `ApiClient` via constructor injection.
+- **Example**:
+  ```typescript
+  export class UserResource extends BaseResource {
+    constructor(client: ApiClient) {
+      super(client);
+    }
+  }
+  ```
+
+### 3. Nested Query Parameter Serialization
+
+Filtering nested data structures requires a specific flattening logic for backend compatibility.
+
+- **Rule**: Nested filter objects MUST be processed recursively using the double-underscore (`__`) delimiter for key concatenation.
+- **Implementation**: Handled by the `buildQuery` utility in `sdk-core`.
+- **Example**: `{ filter: { user: { name: 'test' } } }` -> `?filter__user__name=test`
+
+### 4. Zero-Tolerance for 'any'
+
+Preserve type safety by avoiding the `any` type at all costs.
+
+- **Rule**: The `any` type is strictly forbidden.
+- **Rule**: Use `unknown` or `Record<string, unknown>` for unpredictable payloads.
+
+## Resources
+
+- **Templates**: `templates/resource.tsf`
+- **Examples**: `examples/esm-import.ts`

package/.skills/sdk-core-esm-imports/examples/esm-import.ts

@@ -0,0 +1,27 @@
+/**
+ * @packages/sdk-core/.skills/sdk-core-esm-imports/SKILL.md sdk-core-esm-imports
+ * @description Demonstrates correct ESM relative import usage with .js extensions.
+ */
+
+// CORRECT: ESM requires the explicit .js extension for relative imports.
+import { ApiClient } from './client.js';
+import { BaseResource } from './resource.js';
+import { buildQuery } from '../utils/query.js';
+
+// INCORRECT (Common AI Hallucination): Omitting the extension.
+// import { ApiClient } from './client';
+
+export class ExampleResource extends BaseResource {
+  constructor(client: ApiClient) {
+    super(client);
+  }
+
+  public async list(filters: Record<string, unknown>): Promise<unknown[]> {
+    // Usage of buildQuery to satisfy lint rules and demonstrate pattern
+    const query = buildQuery({ filter: filters });
+    return this.client.request<unknown[]>({
+      method: 'GET',
+      url: `/example?${query}`,
+    });
+  }
+}

package/.skills/sdk-core-esm-imports/templates/resource.tsf

@@ -0,0 +1,30 @@
+/**
+ * @packages/sdk-core/.skills/sdk-core-esm-imports/SKILL.md sdk-core-esm-imports
+ * @packages/generator/src/utils/fragment-tag.ts New SDK Resource Template
+ */
+
+import { BaseResource } from './resource.js';
+import type { ApiClient } from './client.js';
+
+/**
+ * [RESOURCE_NAME] resource implementation.
+ * All SDK resource areas MUST extend BaseResource to inherit request orchestration logic.
+ */
+export class [RESOURCE_NAME] extends BaseResource {
+  /**
+   * @param client - The API client injected via constructor.
+   */
+  constructor(client: ApiClient) {
+    super(client);
+  }
+
+  /**
+   * Example method demonstrating the standard request flow.
+   */
+  public async get[ENTITY](id: string): Promise<[ENTITY]Type> {
+    return this.client.request<[ENTITY]Type>({
+      method: 'GET',
+      url: `/[PATH]/${id}`,
+    });
+  }
+}

package/.skills/sdk-core-query-serialization/SKILL.md

@@ -0,0 +1,36 @@
+# Skill: SDK Core Query Serialization
+
+Expert guide for implementing type-safe SDK resources with nested query parameter serialization. This skill ensures that all SDK modules follow the "Shell-Registry" compatible communication pattern.
+
+## Core Patterns
+
+### 1. Abstract Resource Pattern
+
+All SDK functional areas MUST be organized into 'Resource' classes that extend the `BaseResource` abstract class. This ensures consistent request orchestration and centralized logic for query building.
+
+- **Rule**: Every resource MUST receive an `ApiClient` via constructor injection.
+- **Rule**: Use named exports for all resource classes.
+
+### 2. Nested Query Parameter Serialization
+
+The SDK utilizes a recursive serialization utility to flatten complex filter objects into URL search parameters. This maintains compatibility with the backend's `parseQuery` utility.
+
+- **Delimiter**: Use a double-underscore (`__`) to represent nesting (e.g., `filter: { user: { name: 'Alice' } }` -> `?filter__user__name=Alice`).
+- **Rule**: All `list` or `find` methods in a resource MUST use this serialization logic before making the request.
+
+### 3. NexicalError Strategy
+
+API errors must be captured and transformed into `NexicalError` instances to preserve HTTP status context and provide standardized error messages.
+
+- **Rule**: The SDK must handle both `error` (translation key) and `message` (human-readable) fields from the API response.
+
+## Implementation Standards
+
+- **Zero Any**: Use `unknown` for generic payloads and `Record<string, unknown>` for structured but dynamic filter objects.
+- **ESM Relative Imports**: All internal imports MUST include the `.js` extension.
+- **Named Exports**: Default exports are strictly forbidden in core SDK packages.
+
+## Troubleshooting
+
+- **Serialization Issues**: Verify that the `__` delimiter is correctly applied to nested keys.
+- **204 Responses**: Ensure that HTTP 204 (No Content) responses return a valid `ServiceResponse` structure (e.g., `{ success: true, data: {} as T }`) to satisfy type contracts.

package/.skills/sdk-core-query-serialization/examples/serialization-example.ts

@@ -0,0 +1,44 @@
+/**
+ * Example: Nested Query Parameter Serialization
+ *
+ * This example demonstrates how a complex filter object is flattened
+ * into URL search parameters using the double-underscore (__) delimiter.
+ */
+
+/**
+ * Recursive utility to build query parameters from nested objects.
+ */
+function buildQueryParams(
+  params: URLSearchParams,
+  obj: Record<string, unknown>,
+  prefix: string = '',
+): void {
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}__${key}` : key;
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      buildQueryParams(params, value as Record<string, unknown>, fullKey);
+    } else {
+      params.append(fullKey, String(value));
+    }
+  }
+}
+
+// Example Usage:
+const filters = {
+  status: 'active',
+  user: {
+    role: 'admin',
+    profile: {
+      isVerified: true,
+    },
+  },
+  tags: ['featured', 'new'],
+};
+
+const params = new URLSearchParams();
+buildQueryParams(params, filters);
+
+console.log(params.toString());
+// Output:
+// status=active&user__role=admin&user__profile__isVerified=true&tags=featured%2Cnew

package/.skills/sdk-core-query-serialization/templates/resource.tsf

@@ -0,0 +1,46 @@
+/**
+ * @core/.skills/sdk-core-query-serialization/SKILL.md {import('./resource.js').BaseResource}
+ * 
+ * Fragment Contract:
+ * 1. JSDoc header MUST reference the SDK-Core-Query-Serialization skill.
+ * 2. Exports the `fragment` tagged template literal.
+ * 3. Uses placeholder variables: `${name}`, `${entity}`.
+ */
+
+import { fragment } from '@/lib/generator/fragment.js';
+
+export default fragment`
+import { BaseResource } from '../resource.js';
+import type { ServiceResponse } from '@nexical/sdk-core';
+
+/**
+ * SDK Resource for the ${name} entity.
+ */
+export class ${name}Resource extends BaseResource {
+  /**
+   * List ${entity} records with optional filtering and pagination.
+   * @param filters - Nested filter object using the standard __ delimiter.
+   * @returns A promise resolving to a ServiceResponse containing the results.
+   */
+  public async list(filters?: Record<string, unknown>): Promise<ServiceResponse<unknown[]>> {
+    const params = this.buildQueryParams(filters);
+    return this.client.request<ServiceResponse<unknown[]>>({
+      method: 'GET',
+      path: '/api/${entity}/list',
+      params,
+    });
+  }
+
+  /**
+   * Retrieve a single ${entity} by ID.
+   * @param id - The unique identifier of the record.
+   * @returns A promise resolving to a ServiceResponse containing the entity.
+   */
+  public async get(id: string): Promise<ServiceResponse<unknown>> {
+    return this.client.request<ServiceResponse<unknown>>({
+      method: 'GET',
+      path: `/api/\${entity}/get/\${id}`,
+    });
+  }
+}
+`;

package/.skills/sdk-core-resource-pattern/SKILL.md

@@ -0,0 +1,64 @@
+# Abstract Resource Pattern (sdk-core)
+
+This skill governs the implementation of SDK functional areas (Resources) within the `sdk-core` package. It ensures that all data access logic is organized into standardized, type-safe classes that utilize centralized request orchestration and query serialization.
+
+## Core Mandates
+
+1.  **Abstract Resource Pattern**: All resource classes MUST extend `BaseResource` and receive an `ApiClient` instance via constructor injection.
+2.  **Generic Request Orchestration**: Use the protected `_request<T>` method to wrap the client's request logic. This provides a type-safe interface and ensures consistent error handling.
+3.  **Nested Query Parameter Serialization**: Query parameter serialization MUST use the double-underscore (`__`) delimiter for nested object keys (e.g., `filter__user__name=Alice`) to ensure compatibility with the backend's `parseQuery` utility.
+4.  **ESM Module Imports**: All relative imports MUST include the `.js` extension (e.g., `import { BaseResource } from './resource.js';`).
+5.  **Zero-Tolerance for 'any'**: The use of `any` is strictly forbidden. Use specific interfaces or `unknown` for dynamic data like request bodies or filter values.
+6.  **Infrastructure Named Exports**: Default exports are forbidden. All components MUST be exported as named members to ensure explicit importing and better tree-shaking.
+7.  **Auth Strategy Integration**: Authentication headers MUST be resolved dynamically via the injected `AuthStrategy` in the `ApiClient`.
+8.  **204 No Content Compatibility**: Handlers MUST explicitly check for 204 status codes and return an empty object (`{}`) cast to the expected type `T`.
+9.  **NexicalError Handling**: All API errors MUST be wrapped in the `NexicalError` class to preserve HTTP status context.
+10. **Base URL Normalization**: Base URLs MUST be normalized in the constructor to remove trailing slashes to prevent path concatenation errors.
+11. **Default Credential Inclusion**: The `ApiClient` MUST default to 'include' for credentials unless explicitly overridden to ensure cookies/auth headers are sent in browser environments.
+
+## Implementation Workflow
+
+### 1. Define the Resource Class
+
+Create a new file in `src/resources/` (or similar) that extends `BaseResource`.
+
+```typescript
+import { BaseResource } from '../resource.js';
+import type { ApiClient } from '../client.js';
+
+export class MyResource extends BaseResource {
+  constructor(client: ApiClient) {
+    super(client);
+    // BaseResource constructor handles Base URL Normalization
+  }
+}
+```
+
+### 2. Implement Operation Methods
+
+Use the `_request<T>` wrapper for all API calls.
+
+```typescript
+export class MyResource extends BaseResource {
+  async get(id: string): Promise<MyDataType> {
+    return this._request<MyDataType>('GET', `/my-resource/${id}`);
+  }
+}
+```
+
+### 3. Handle Queries and Filters
+
+Use the `buildQuery` method (provided by `BaseResource`) which implements the double-underscore serialization logic.
+
+```typescript
+async list(filters: Record<string, unknown> = {}): Promise<MyDataType[]> {
+  const query = this.buildQuery(filters);
+  return this._request<MyDataType[]>('GET', `/my-resource${query}`);
+}
+```
+
+## Reference Patterns
+
+- **Serialization**: Refer to `examples/serialization.ts` for nested object flattening logic.
+- **ESM Imports**: Refer to `examples/esm-imports.ts` for correct import syntax.
+- **Resource Structure**: Refer to `templates/resource.tsf` for the standard class boilerplate.

package/.skills/sdk-core-resource-pattern/examples/esm-imports.ts

@@ -0,0 +1,24 @@
+/**
+ * Example: ESM Module Imports (.js extension)
+ *
+ * Requirement: All relative imports MUST include the '.js' extension.
+ * Reason: ESM runtime requirements and Bun/Node.js compatibility.
+ */
+
+// CORRECT: Including .js extension even for .ts source files
+import { ApiClient as _ApiClient } from './client.js';
+import { BaseResource } from './resource.js';
+import { NexicalError as _NexicalError } from '../errors/index.js';
+
+// INCORRECT: Missing extension (will fail in ESM)
+// import { ApiClient } from './client';
+
+// INCORRECT: Using .ts extension (not supported by ESM loaders)
+// import { ApiClient } from './client.ts';
+
+export class UserResource extends BaseResource {
+  // Example usage of BaseResource to avoid empty class if needed
+  async getProfile() {
+    return this._request('GET', '/profile');
+  }
+}

package/.skills/sdk-core-resource-pattern/examples/serialization.ts

@@ -0,0 +1,41 @@
+/**
+ * Example: Nested Query Parameter Serialization
+ *
+ * Requirement: Flatten nested objects using double-underscore (__) delimiter.
+ * Compatibility: backend parseQuery utility.
+ */
+
+const filters = {
+  status: 'active',
+  user: {
+    name: 'Alice',
+    role: {
+      type: 'admin',
+    },
+  },
+};
+
+// Resulting query string should look like:
+// ?status=active&user__name=Alice&user__role__type=admin
+
+/**
+ * Simplified logic representation of BaseResource.buildQuery
+ */
+function buildQuery(filters: Record<string, unknown>, prefix = ''): string {
+  const parts: string[] = [];
+
+  for (const [key, value] of Object.entries(filters)) {
+    const fullKey = prefix ? `${prefix}__${key}` : key;
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      // Recursively flatten nested objects
+      parts.push(buildQuery(value as Record<string, unknown>, fullKey));
+    } else {
+      parts.push(`${fullKey}=${encodeURIComponent(String(value))}`);
+    }
+  }
+
+  return parts.join('&');
+}
+
+console.info('?' + buildQuery(filters));

package/.skills/sdk-core-resource-pattern/templates/resource-method.tsf

@@ -0,0 +1,22 @@
+/**
+ * @fragment ResourceMethodTemplate
+ * @description Standard implementation for a resource operation using _request and buildQuery.
+ */
+
+/* PHANTOM_DECLARATIONS_START */
+import { BaseResource } from '../resource.js';
+class MyResource extends BaseResource {
+  _request<T>(m: string, p: string, b?: unknown): Promise<T> { return {} as any; }
+}
+interface MyDataType { id: string; }
+/* PHANTOM_DECLARATIONS_END */
+
+/**
+ * ${Summary}
+ * @param filters - Optional filters for the request.
+ * @returns A promise resolving to the data.
+ */
+async ${methodName}(filters: Record<string, unknown> = {}): Promise<${ReturnType}> {
+  const query = this.buildQuery(filters);
+  return this._request<${ReturnType}>('${verb}', `${path}${query}`);
+}

package/.skills/sdk-core-resource-pattern/templates/resource.tsf

@@ -0,0 +1,23 @@
+/**
+ * @fragment ResourceTemplate
+ * @description Standard boilerplate for an SDK Resource class extending BaseResource.
+ */
+
+import { BaseResource } from '../resource.js';
+import type { ApiClient } from '../client.js';
+
+/* PHANTOM_DECLARATIONS_START */
+interface MyDataType { id: string; name: string; }
+/* PHANTOM_DECLARATIONS_END */
+
+export class ${ResourceName}Resource extends BaseResource {
+  /**
+   * Creates a new instance of ${ResourceName}Resource.
+   * @param client - The ApiClient instance for request orchestration.
+   */
+  constructor(client: ApiClient) {
+    super(client);
+  }
+
+  // Implementation methods follow...
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexical/sdk-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "src/index.ts",