@harperfast/template-react-studio 1.2.2 → 1.3.1

package/skills/adding-tables-with-schemas.md

@@ -1,34 +0,0 @@
-# Adding Tables to Harper
-
-To add tables to a Harper database, follow these guidelines:
-
-1. **Dedicated Schema Files**: Prefer having a dedicated schema `.graphql` file for each table. Check the `config.yaml` file under `graphqlSchema.files` to see how it's configured. It typically accepts wildcards (e.g., `schemas/*.graphql`), but may be configured to point at a single file.
-
-2. **Directives**: All available directives for defining your schema are defined in `node_modules/harperdb/schema.graphql`. Common directives include `@table`, `@export`, `@primaryKey`, `@indexed`, and `@relationship`.
-
-3. **Defining Relationships**: You can link tables together using the `@relationship` directive. For more details, see the [Defining Relationships](defining-relationships.md) skill.
-
-4. **Automatic APIs**: If you add `@table @export` to a schema type, Harper automatically sets up REST and WebSocket APIs for basic CRUD operations against that table. For a detailed list of available endpoints and how to use them, see the [Automatic REST APIs](automatic-apis.md) skill.
-
-   - `GET /{TableName}`: Describes the schema itself.
-   - `GET /{TableName}/`: Lists all records (supports filtering, sorting, and pagination via query parameters). See the [Querying REST APIs](querying-rest-apis.md) skill for details.
-   - `GET /{TableName}/{id}`: Retrieves a single record by its ID.
-   - `POST /{TableName}/`: Creates a new record.
-   - `PUT /{TableName}/{id}`: Updates an existing record.
-   - `PATCH /{TableName}/{id}`: Performs a partial update on a record.
-   - `DELETE /{TableName}/`: Deletes all records or filtered records.
-   - `DELETE /{TableName}/{id}`: Deletes a single record by its ID.
-
-### Example
-
-In `schemas/ExamplePerson.graphql`:
-
-```graphql
-type ExamplePerson @table @export {
-	id: ID @primaryKey
-	name: String
-	tag: String @indexed
-}
-```
-
-Tip: if you are going to [extend the table](./extending-tables.md) in your resources, then do not `@export` the table from the schema.

package/skills/automatic-apis.md

@@ -1,53 +0,0 @@
-# Automatic APIs in Harper
-
-When you define a GraphQL type with the `@table` and `@export` directives, Harper automatically generates a fully-functional REST API and WebSocket interface for that table. This allows for immediate CRUD (Create, Read, Update, Delete) operations and real-time updates without writing any additional code.
-
-## Enabling Automatic APIs
-
-To enable the automatic REST and WebSocket APIs for a table, ensure your GraphQL schema includes the `@export` directive:
-
-```graphql
-type MyTable @table @export {
-	id: ID @primaryKey
-	# ... other fields
-}
-```
-
-## Available REST Endpoints
-
-The following endpoints are automatically created for a table named `TableName` (Note: Paths are **case-sensitive**, so `GET /TableName/` is valid while `GET /tablename/` is not):
-
-- **Describe Schema**: `GET /{TableName}`
-  Returns the schema definition and metadata for the table.
-- **List Records**: `GET /{TableName}/`
-  Lists all records in the table. This endpoint supports advanced filtering, sorting, and pagination. For more details, see the [Querying REST APIs](querying-rest-apis.md) skill.
-- **Get Single Record**: `GET /{TableName}/{id}`
-  Retrieves a single record by its primary key (`id`).
-- **Create Record**: `POST /{TableName}/`
-  Creates a new record. The request body should be a JSON object containing the record data.
-- **Update Record (Full)**: `PUT /{TableName}/{id}`
-  Replaces the entire record at the specified `id` with the provided JSON data.
-- **Update Record (Partial)**: `PATCH /{TableName}/{id}`
-  Updates only the specified fields of the record at the given `id`.
-- **Delete All/Filtered Records**: `DELETE /{TableName}/`
-  Deletes all records in the table, or a subset of records if filtering parameters are provided.
-- **Delete Single Record**: `DELETE /{TableName}/{id}`
-  Deletes the record with the specified `id`.
-
-## Automatic WebSockets
-
-In addition to REST endpoints, Harper also stands up WebSocket interfaces for exported tables. When you connect to the table's endpoint via WebSocket, you will automatically receive events whenever updates are made to that table.
-
-- **WebSocket Endpoint**: `ws://your-harper-instance/{TableName}`
-
-This is the easiest way to add real-time capabilities to your application. For more complex real-time needs, see the [Real-time Applications](real-time-apps.md) skill.
-
-## Filtering and Querying
-
-The `GET /{TableName}/` and `DELETE /{TableName}/` endpoints can be filtered using query parameters. While basic equality filters are straightforward, Harper supports a rich set of operators, sorting, and pagination.
-
-For a comprehensive guide on advanced querying, see the [Querying REST APIs](querying-rest-apis.md) skill.
-
-## Customizing Resources
-
-If the automatic APIs don't behave how you need, then you can look to [customize the resources](./custom-resources.md).

package/skills/automatic-rest-apis.md

@@ -1,41 +0,0 @@
-# Automatic REST APIs in HarperDB
-
-When you define a GraphQL type with the `@table` and `@export` directives, HarperDB automatically generates a fully-functional REST API for that table. This allows for immediate CRUD (Create, Read, Update, Delete) operations without writing any additional code.
-
-## Enabling REST APIs
-
-To enable the automatic REST API for a table, ensure your GraphQL schema includes the `@export` directive:
-
-```graphql
-type MyTable @table @export {
-	id: ID @primaryKey
-	# ... other fields
-}
-```
-
-## Available Endpoints
-
-The following endpoints are automatically created for a table named `TableName` (Note: Paths are **case-sensitive**, so `GET /TableName/` is valid while `GET /tablename/` is not):
-
-- **Describe Schema**: `GET /{TableName}`
-  Returns the schema definition and metadata for the table.
-- **List Records**: `GET /{TableName}/`
-  Lists all records in the table. This endpoint supports advanced filtering, sorting, and pagination. For more details, see the [Querying REST APIs](querying-rest-apis.md) skill.
-- **Get Single Record**: `GET /{TableName}/{id}`
-  Retrieves a single record by its primary key (`id`).
-- **Create Record**: `POST /{TableName}/`
-  Creates a new record. The request body should be a JSON object containing the record data.
-- **Update Record (Full)**: `PUT /{TableName}/{id}`
-  Replaces the entire record at the specified `id` with the provided JSON data.
-- **Update Record (Partial)**: `PATCH /{TableName}/{id}`
-  Updates only the specified fields of the record at the given `id`.
-- **Delete All/Filtered Records**: `DELETE /{TableName}/`
-  Deletes all records in the table, or a subset of records if filtering parameters are provided.
-- **Delete Single Record**: `DELETE /{TableName}/{id}`
-  Deletes the record with the specified `id`.
-
-## Filtering and Querying
-
-The `GET /{TableName}/` and `DELETE /{TableName}/` endpoints can be filtered using query parameters. While basic equality filters are straightforward, HarperDB supports a rich set of operators, sorting, and pagination.
-
-For a comprehensive guide on advanced querying, see the [Querying REST APIs](querying-rest-apis.md) skill.

package/skills/caching.md

@@ -1,113 +0,0 @@
-# Harper Caching
-
-Harper includes integrated support for **caching data from external sources**, enabling high-performance, low-latency cache storage that is fully queryable and interoperable with your applications. With built-in caching capabilities and distributed responsiveness, Harper makes an ideal **data caching server** for both edge and centralized use cases.
-
----
-
-## What is Harper Caching?
-
-Harper caching lets you store **cached content** in standard tables, enabling you to:
-
-- Expose cached entries as **queryable structured data** (e.g., JSON or CSV)
-- Serve data to clients with **flexible formats and custom querying**
-- Manage cache control with **timestamps and ETags** for downstream caching layers
-- Implement **active or passive caching** patterns depending on your source and invalidation strategy
-
----
-
-## Configuring a Cache Table
-
-Define a cache table in your `schema.graphql`:
-
-```graphql
-type MyCache @table(expiration: 3600) @export {
-	id: ID @primaryKey
-}
-```
-
-- `expiration` is defined in seconds
-- Expired records are refreshed on access
-- Evicted records are removed after expiration
-
----
-
-## Connecting an External Source
-
-Create a resource:
-
-```js
-import { Resource } from 'harperdb';
-
-export class ThirdPartyAPI extends Resource {
-	async get() {
-		const id = this.getId();
-		const response = await fetch(`https://api.example.com/items/${id}`);
-		if (!response.ok) {
-			throw new Error('Source fetch failed');
-		}
-		return await response.json();
-	}
-}
-```
-
-Attach it to your table:
-
-```js
-import { tables } from 'harperdb';
-import { ThirdPartyAPI } from './ThirdPartyAPI.js';
-
-const { MyCache } = tables;
-MyCache.sourcedFrom(ThirdPartyAPI);
-```
-
----
-
-## Cache Behavior
-
-1. Fresh data is returned immediately
-2. Missing or stale data triggers a fetch
-3. Concurrent misses are deduplicated
-
----
-
-## Active Caching
-
-Use `subscribe()` to proactively update or invalidate cache entries:
-
-```js
-class MyAPI extends Resource {
-	async *subscribe() {
-		// stream updates
-	}
-}
-```
-
-See [Real Time Apps](real-time-apps.md) for more details.
-
----
-
-## Write-Through Caching
-
-Propagate updates upstream:
-
-```js
-class ThirdPartyAPI extends Resource {
-	async put(data) {
-		await fetch(`https://some-api.com/${this.getId()}`, {
-			method: 'PUT',
-			body: JSON.stringify(data),
-		});
-	}
-}
-```
-
----
-
-## Summary
-
-Harper Caching allows you to:
-
-- Cache external APIs efficiently
-- Query cached data like native tables
-- Prevent cache stampedes
-- Build real-time or write-through caches

package/skills/checking-authentication.md

@@ -1,281 +0,0 @@
-# Checking Authentication and Sessions in this app (Harper Resources)
-
-This project uses Harper Resource classes with cookie-backed sessions to enforce authentication and authorization. Below are the concrete patterns used across resources like `resources/me.ts`, `resources/signIn.ts`, `resources/signOut.ts`, and protected endpoints such as `resources/downloadAlbumArtwork.ts`.
-
-Important: To actually enforce sessions (even on localhost), Harper must not auto-authorize the local loopback as the superuser. Ensure the following in your Harper config (see `~/hdb/harperdb-config.yaml`):
-
-```yaml
-authentication:
-  authorizeLocal: false
-  enableSessions: true
-```
-
-With `authorizeLocal: true`, all local requests would be auto-authorized as the superuser, bypassing these checks. We keep it off to ensure session checks are respected.
-
-## Public vs protected routes
-
-- Public resources explicitly allow the method via `allowRead()` or `allowCreate()` or similara returning `true`.
-- Protected handlers perform checks up-front using the current session user (and, for privileged actions, a helper like `ensureSuperUser`).
-
-## Creating a session (sign in)
-
-Pattern from `resources/signIn.ts`:
-
-```ts
-import { type Context, type RequestTargetOrId, Resource } from 'harperdb';
-
-export interface LoginBody {
-	username?: string;
-	password?: string;
-}
-
-export class SignIn extends Resource {
-	static loadAsInstance = false;
-
-	allowCreate() {
-		return true; // public endpoint
-	}
-
-	async post(_target: RequestTargetOrId, data: LoginBody) {
-		const errors: string[] = [];
-		if (!data.username) { errors.push('username'); }
-		if (!data.password) { errors.push('password'); }
-		if (errors.length) {
-			return new Response(
-				`Please include the ${errors.join(' and ')} in your request.`,
-				{ status: 400 },
-			);
-		}
-
-		const context = this.getContext() as Context as any;
-		try {
-			await context.login(data.username, data.password);
-		} catch {
-			return new Response('Please check your credentials and try again.', {
-				status: 403,
-			});
-		}
-		return new Response('Welcome back!', { status: 200 });
-	}
-}
-```
-
-- `context.login(username, password)` creates a session and sets the session cookie on the response.
-- Missing fields → `400 Bad Request`.
-- Invalid credentials → `403 Forbidden` (don’t leak which field was wrong).
-
-## Reading the current user (who am I)
-
-Pattern from `resources/me.ts`:
-
-```ts
-import { Resource } from 'harperdb';
-
-export class Me extends Resource {
-	static loadAsInstance = false;
-
-	allowRead() {
-		return true; // public: returns data only if session exists
-	}
-
-	async get() {
-		const user = this.getCurrentUser?.();
-		if (!user?.username) {
-			// Not signed in; return 200 with no body to make polling simple on the client
-			return new Response(null, { status: 200 });
-		}
-		return {
-			active: user.active,
-			role: user.role,
-			username: user.username,
-			created: user.__createdtime__,
-			updated: user.__updatedtime__,
-		};
-	}
-}
-```
-
-- Use `this.getCurrentUser?.()` to access the session’s user (if any).
-- It may be `undefined` when unauthenticated. Handle that case explicitly.
-
-## Destroying a session (sign out)
-
-Pattern from `resources/signOut.ts`:
-
-```ts
-import { type Context, Resource } from 'harperdb';
-
-export class SignOut extends Resource {
-	static loadAsInstance = false;
-
-	allowCreate() {
-		return true; // public endpoint, but requires a session to actually act
-	}
-
-	async post() {
-		const user = this.getCurrentUser();
-		if (!user?.username) {
-			return new Response('Not signed in.', { status: 401 });
-		}
-
-		const context = this.getContext() as Context as any;
-		await context.session?.delete?.(context.session.id);
-		return new Response('Signed out successfully.', { status: 200 });
-	}
-}
-```
-
-- If the request has no session, return `401 Unauthorized`.
-- Otherwise delete the current session via `context.session.delete(sessionId)`.
-
-## Protecting privileged endpoints
-
-For admin-only or otherwise privileged actions, use the `ensureSuperUser` helper with the current user.
-
-```ts
-import {
-	RequestTarget,
-	type RequestTargetOrId,
-	Resource,
-	tables,
-} from 'harperdb';
-import { ensureSuperUser } from './common/ensureSuperUser.ts';
-
-export class DoSomethingInteresting extends Resource {
-	static loadAsInstance = false;
-
-	async get(target: RequestTargetOrId) {
-		ensureSuperUser(this.getCurrentUser());
-		// … fetch and return the artwork
-	}
-}
-```
-
-`ensureSuperUser` throws a `403` if the user is not a super user:
-
-```ts
-import { type User } from 'harperdb';
-
-export function ensureSuperUser(user: User | undefined) {
-	if (!user?.role?.permission?.super_user) {
-		let error = new Error('You do not have permission to perform this action.');
-		(error as any).statusCode = 403;
-		throw error;
-	}
-}
-```
-
-## Status code conventions used here
-
-- 200: Successful operation. For `GET /me`, a `200` with empty body means “not signed in”.
-- 400: Missing required fields (e.g., username/password on sign-in).
-- 401: No current session for an action that requires one (e.g., sign out when not signed in).
-- 403: Authenticated but not authorized (bad credentials on login attempt, or insufficient privileges).
-
-## Client considerations
-
-- Sessions are cookie-based; the server handles setting and reading the cookie via Harper. If you make cross-origin requests, ensure the appropriate `credentials` mode and CORS settings.
-- If developing locally, double-check the server config still has `authentication.authorizeLocal: false` to avoid accidental superuser bypass.
-
-## Token-based auth (JWT + refresh token) for non-browser clients
-
-Cookie-backed sessions are great for browser flows. For CLI tools, mobile apps, or other non-browser clients, it’s often easier to use **explicit tokens**:
-
-- **JWT (`operation_token`)**: short-lived bearer token used to authorize API requests.
-- **Refresh token (`refresh_token`)**: longer-lived token used to mint a new JWT when it expires.
-
-This project includes two Resource patterns for that flow:
-
-### Issuing tokens: `IssueTokens`
-
-**Description / use case:** Generate `{ refreshToken, jwt }` either:
-
-- with an existing Authorization token (either Basic Auth or a JWT) and you want to issue new tokens, or
-- from an explicit `{ username, password }` payload (useful for direct “login” from a CLI/mobile client).
-
-```
-js
-export class IssueTokens extends Resource {
-static loadAsInstance = false;
-
-	async get(target) {
-		const { refresh_token: refreshToken, operation_token: jwt } =
-			await databases.system.hdb_user.operation(
-				{ operation: 'create_authentication_tokens' },
-				this.getContext(),
-			);
-		return { refreshToken, jwt };
-	}
-
-	async post(target, data) {
-		if (!data.username || !data.password) {
-			throw new Error('username and password are required');
-		}
-
-		const { refresh_token: refreshToken, operation_token: jwt } =
-			await databases.system.hdb_user.operation({
-				operation: 'create_authentication_tokens',
-				username: data.username,
-				password: data.password,
-			});
-		return { refreshToken, jwt };
-	}
-}
-```
-
-**Recommended documentation notes to include:**
-
-- `GET` variant: intended for “I already have an Authorization token, give me new tokens”.
-- `POST` variant: intended for “I have credentials, give me tokens”.
-- Response shape:
-  - `refreshToken`: store securely (long-lived).
-  - `jwt`: attach to requests (short-lived).
-
-### Refreshing a JWT: `RefreshJWT`
-
-**Description / use case:** When the JWT expires, the client uses the refresh token to get a new JWT without re-supplying username/password.
-
-```
-js
-export class RefreshJWT extends Resource {
-static loadAsInstance = false;
-
-	async post(target, data) {
-		if (!data.refreshToken) {
-			throw new Error('refreshToken is required');
-		}
-
-		const { operation_token: jwt } = await databases.system.hdb_user.operation({
-			operation: 'refresh_operation_token',
-			refresh_token: data.refreshToken,
-		});
-		return { jwt };
-	}
-}
-```
-
-**Recommended documentation notes to include:**
-
-- Requires `refreshToken` in the request body.
-- Returns a new `{ jwt }`.
-- If refresh fails (expired/revoked), client must re-authenticate (e.g., call `IssueTokens.post` again).
-
-### Suggested client flow (high-level)
-
-1. **Sign in (token flow)**
-   - POST /IssueTokens/ with a body of `{ "username": "your username", "password": "your password" }` or GET /IssueTokens/ with an existing Authorization token.
-   - Receive `{ jwt, refreshToken }` in the response
-2. **Call protected APIs**
-   - Send the JWT with each request in the Authorization header (as your auth mechanism expects)
-3. **JWT expires**
-   - POST /RefreshJWT/ with a body of `{ "refreshToken": "your refresh token" }`.
-   - Receive `{ jwt }` in the response and continue
-
-## Quick checklist
-
-- [ ] Public endpoints explicitly `allowRead`/`allowCreate` as needed.
-- [ ] Sign-in uses `context.login` and handles 400/403 correctly.
-- [ ] Protected routes call `ensureSuperUser(this.getCurrentUser())` (or another role check) before doing work.
-- [ ] Sign-out verifies a session and deletes it.
-- [ ] `authentication.authorizeLocal` is `false` and `enableSessions` is `true` in Harper config.
-- [ ] If using tokens: `IssueTokens` issues `{ jwt, refreshToken }`, `RefreshJWT` refreshes `{ jwt }` with a `refreshToken`.

package/skills/custom-resources.md

@@ -1,86 +0,0 @@
-# Custom Resources in Harper
-
-Custom Resources allow you to define your own REST endpoints with custom logic by writing JavaScript or TypeScript code. This is useful when the automatic CRUD operations provided by `@table @export` are not enough.
-
-Harper supports [TypeScript Type Stripping](typescript-type-stripping.md), allowing you to use TypeScript directly without additional build tools on supported Node.js versions.
-
-## Do you need a custom resource?
-
-Exported tables have [automatic APIs](./automatic-apis.md) as a part of them. These APIs may be enough for what you need. Take a look at [extendings tables](./extending-tables.md) to learn more about resources with a backing table.
-
-## Defining a Custom Resource
-
-To create a custom resource:
-
-1. Create a `.ts` (or `.js`) file in the directory specified by `jsResource` in `config.yaml` (usually `resources/`).
-2. Export a class that extends the `Resource` class from the `harperdb` module.
-
-### Example: `resources/greeting.ts`
-
-```typescript
-import { type RecordObject, type RequestTargetOrId, Resource } from 'harperdb';
-
-interface GreetingRecord {
-	greeting: string;
-}
-
-export class Greeting extends Resource<GreetingRecord> {
-	// Set to false if you want Harper to manage the instance lifecycle
-	static loadAsInstance = false;
-
-	async get(target?: RequestTargetOrId): Promise<GreetingRecord> {
-		return { greeting: 'Hello from a custom GET endpoint!' };
-	}
-
-	async post(
-		target: RequestTargetOrId,
-		newRecord: Partial<GreetingRecord & RecordObject>,
-	): Promise<GreetingRecord> {
-		// Custom logic for handling POST requests
-		return { greeting: `Hello, ${newRecord.greeting || 'stranger'}!` };
-	}
-}
-```
-
-## Supported HTTP Methods
-
-You can implement any of the following methods in your resource class to handle the corresponding HTTP requests:
-
-- `get(target?: RequestTargetOrId)`
-- `post(target: RequestTargetOrId, body: any)`
-- `put(target: RequestTargetOrId, body: any)`
-- `patch(target: RequestTargetOrId, body: any)`
-- `delete(target: RequestTargetOrId)`
-
-The `target` parameter typically contains the ID or sub-path from the URL.
-
-## Accessing Tables
-
-Within your custom resource, you can easily access your database tables using the `tables` object:
-
-```typescript
-import { Resource, tables } from 'harperdb';
-
-export class MyCustomResource extends Resource {
-	async get() {
-		// Query a table
-		const results = await tables.ExamplePeople.list();
-		return results;
-	}
-}
-```
-
-## Configuration
-
-Ensure your `config.yaml` is configured to load your resources:
-
-```yaml
-jsResource:
-  files: 'resources/*.ts'
-```
-
-Once defined and configured, your resource will be available at a REST endpoint matching the class name exactly.
-
-### Case Sensitivity
-
-Paths in Harper are **case-sensitive**. A resource class named `MyResource` will be accessible only at `/MyResource/`, not `/myresource/`.

package/skills/defining-relationships.md

@@ -1,71 +0,0 @@
-# Defining Relationships in Harper
-
-Harper allows you to define relationships between tables using the `@relationship` directive in your GraphQL schema. This enables powerful features like automatic joins when querying through REST APIs.
-
-## The `@relationship` Directive
-
-The `@relationship` directive is applied to a field in your GraphQL type and takes two optional arguments:
-
-- `from`: The field in the _current_ table that holds the foreign key.
-- `to`: The field in the _related_ table that holds the foreign key.
-
-## Relationship Types
-
-### One-to-One and Many-to-One
-
-To define a relationship where the current table holds the foreign key, use the `from` argument.
-
-```graphql
-type Author @table @export {
-	id: ID @primaryKey
-	name: String
-}
-
-type Book @table @export {
-	id: ID @primaryKey
-	title: String
-	authorId: ID
-	# This field resolves to an Author object using authorId
-	author: Author @relationship(from: "authorId")
-}
-```
-
-### One-to-Many and Many-to-Many
-
-To define a relationship where the _related_ table holds the foreign key, use the `to` argument. The field type should be an array.
-
-```graphql
-type Author @table @export {
-	id: ID @primaryKey
-	name: String
-	# This field resolves to an array of Books that have this author's ID in their authorId field
-	books: [Book] @relationship(to: "authorId")
-}
-
-type Book @table @export {
-	id: ID @primaryKey
-	title: String
-	authorId: ID
-}
-```
-
-## Querying Relationships
-
-Once relationships are defined, you can use them in your REST API queries using dot syntax.
-
-Example:
-`GET /Book/?author.name=Harper`
-
-This will automatically perform a join and return all books whose author's name is "Harper".
-
-You can also use the `select()` operator to include related data in the response:
-
-`GET /Author/?select(name,books(title))`
-
-This returns authors with their names and a list of their books (only the titles).
-
-## Benefits of `@relationship`
-
-- **Simplified Queries**: No need for complex manual joins in your code.
-- **Efficient Data Fetching**: Harper optimizes relationship lookups.
-- **Improved API Discoverability**: Related data structures are clearly defined in your schema.