@harperfast/template-react-studio 0.9.3 → 0.11.0

package/AGENTS.md

@@ -7,10 +7,12 @@ This repository contains "skills" that guide AI agents in developing Harper appl
 - [Adding Tables](skills/adding-tables.md): Learn how to define schemas and enable automatic REST APIs for your database tables.
 - [Automatic REST APIs](skills/automatic-rest-apis.md): Details on the CRUD endpoints automatically generated for exported tables.
 - [Querying REST APIs](skills/querying-rest-apis.md): How to use filters, operators, sorting, and pagination in REST requests.
+- [Programmatic Table Requests](skills/programmatic-table-requests.md): How to use filters, operators, sorting, and pagination in programmatic table requests.
 - [Custom Resources](skills/custom-resources.md): How to define custom REST endpoints using JavaScript or TypeScript (Note: Paths are case-sensitive).
 - [Extending Table Resources](skills/extending-tables.md): Adding custom logic to automatically generated table resources.
 - [Defining Relationships](skills/defining-relationships.md): Using the `@relationship` directive to link tables.
 - [Real-time Applications](skills/real-time-apps.md): Implementing WebSockets and Pub/Sub for live data updates.
 - [TypeScript Type Stripping](skills/typescript-type-stripping.md): Using TypeScript directly without build tools via Node.js Type Stripping.
 - [Handling Binary Data](skills/handling-binary-data.md): How to store and serve binary data like images or MP3s.
-- [Checking Authentication](skills/checking-authentication.md): How to use `this.getCurrentUser()` to verify user identity and roles.
+- [Serving Web Content](skills/serving-web-content): Two ways to serve web content from a Harper application.
+- [Checking Authentication](skills/checking-authentication.md): How to use sessions to verify user identity and roles.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@harperfast/template-react-studio",
-	"version": "0.9.3",
+	"version": "0.11.0",
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {},

package/schemas/exampleCat.graphql

@@ -0,0 +1,6 @@
+## This table is @export'ed, which means API endpoints are stood up for it automatically.
+type ExampleCat @table @export {
+	id: ID @primaryKey # Here we define primary key (must be one)
+	name: String # we can define any other attributes here
+	tag: String @indexed # we can specify any attributes that should be indexed
+}

package/skills/adding-tables.md

@@ -21,12 +21,14 @@ To add tables to a Harper database, follow these guidelines:
 
 ### Example
 
-In `schemas/ExampleTable.graphql`:
+In `schemas/ExamplePerson.graphql`:
 
 ```graphql
-type ExampleTable @table @export {
+type ExamplePerson @table @export {
 	id: ID @primaryKey
 	name: String
-	email: String @indexed
+	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/checking-authentication.md

@@ -1,52 +1,186 @@
-# Checking Authentication in HarperDB
+# Checking Authentication and Sessions in this app (HarperDB Resources)
 
-Custom resources and table resource overrides often need to restrict access based on the current user's identity or role. HarperDB provides the `this.getCurrentUser()` method within resource classes to access information about the authenticated user making the request.
+This project uses HarperDB 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`.
 
-## Using `this.getCurrentUser()`
+Important: To actually enforce sessions (even on localhost), HarperDB must not auto-authorize the local loopback as the superuser. Ensure the following in your HarperDB config (see `~/hdb/harperdb-config.yaml`):
 
-The `this.getCurrentUser()` method returns an object containing details about the authenticated user, such as their username and role. If the request is unauthenticated, it may return `null` or `undefined`.
+```yaml
+authentication:
+  authorizeLocal: false
+  enableSessions: true
+```
 
-### Example: Role-Based Access Control
+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.
 
-You can check the user's role to determine if they have permission to perform a specific action.
+## Public vs protected routes
 
-```typescript
-import { RequestTargetOrId, Resource } from 'harperdb';
+- 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`).
 
-export class MyResource extends Resource {
-	async post(target: RequestTargetOrId, record: any) {
-		const user = this.getCurrentUser();
+## 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;
 
-		// Check if the user has the 'super_user' role
-		if (user?.role?.role !== 'super_user') {
-			throw {
-				message: 'Only super users are allowed to make changes',
-				statusCode: 403,
-			};
+	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 },
+			);
 		}
 
-		return super.post(target, record);
+		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 });
 	}
 }
 ```
 
-## Handling Unauthenticated Requests
+- `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';
 
-Always ensure you handle cases where `this.getCurrentUser()` returns `null`, especially if your resource is accessible to unauthenticated users.
+export class Me extends Resource {
+	static loadAsInstance = false;
 
-```typescript
-const user = this.getCurrentUser();
-if (!user) {
-	throw {
-		message: 'Authentication required',
-		statusCode: 401,
-	};
+	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__,
+		};
+	}
 }
 ```
 
-## User Object Structure
+- 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 HarperDB. 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.
 
-The object returned by `this.getCurrentUser()` typically includes:
+## Quick checklist
 
-- `username`: The username of the authenticated user.
-- `role`: An object containing role information, including the `role` name itself (e.g., `user.role.role`).
+- [ ] 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 HarperDB config.

package/skills/extending-tables.md

@@ -54,3 +54,13 @@ export class ExamplePeople extends tables.ExamplePeople<ExamplePerson> {
 ## Important Note
 
 When you extend a table resource, HarperDB uses your custom class for all REST API interactions with that table. Make sure to call `super[method]` if you still want the default behavior to occur after your custom logic.
+
+Extended tables do not need to be `@export`ed in their schema .graphql.
+
+```graphql
+type ExamplePerson @table {
+	id: ID @primaryKey
+	name: String
+	tag: String @indexed
+}
+```

package/skills/handling-binary-data.md

@@ -8,7 +8,7 @@ In a custom resource or a table resource override, you can intercept the incomin
 
 ### Example
 
-Suppose you have a table with a `Blob` field named `data`. You can use `Buffer.from(string, 'base64')` to perform the conversion.
+Suppose you have a table with a `Blob` field named `data`. You can use `Buffer.from(string, 'base64')` to perform the conversion to a buffer, and then use Harper's `createBlob` function to turn that buffer into a blob with a type such as `{ type: 'image/jpeg' }`.
 
 ```typescript
 import { RequestTargetOrId, Resource } from 'harperdb';
@@ -17,7 +17,9 @@ export class MyResource extends Resource {
 	async post(target: RequestTargetOrId, record: any) {
 		if (record.data) {
 			// Convert base64-encoded string to a Buffer
-			record.data = Buffer.from(record.data, 'base64');
+			record.data = createBlob(Buffer.from(record.artwork, 'base64'), {
+				type: 'image/jpeg',
+			});
 		}
 		// Call the super method to perform the actual storage
 		return super.post(target, record);
@@ -29,9 +31,9 @@ export class MyResource extends Resource {
 
 When you want to serve binary data (like an image or an MP3 file) back to the client, you can return a response object from your resource's `get` method. This object should include the appropriate `status`, `headers`, and the binary data itself in the `body`.
 
-### Example: Streaming an MP3 File
+### Example: Responding with a JPEG File
 
-In this example, we retrieve a track from the database. If it contains binary data in the `data` field, we return it with the `audio/mpeg` content type.
+In this example, we retrieve a thumbnail from the database. If it contains binary data in the `data` field, we return it with the `image/jpeg` content type.
 
 ```typescript
 import { RequestTarget, RequestTargetOrId, Resource } from 'harperdb';
@@ -42,23 +44,23 @@ export class TrackResource extends Resource {
 		if (!id) {
 			return super.get(target);
 		}
-		const track = await super.get(target) as any;
-		if (track?.data) {
+		const thumbnail = await super.get(target);
+		if (thumbnail?.data) {
 			return {
 				status: 200,
 				headers: {
-					'Content-Type': 'audio/mpeg',
-					'Content-Disposition': `inline; filename="${track.name}.mp3"`,
+					'Content-Type': 'image/jpeg',
+					'Content-Disposition': `inline; filename="${thumbnail.name}.jpg"`,
 				},
-				body: track.data,
+				body: thumbnail.data,
 			};
 		}
-		return track;
+		return thumbnail;
 	}
 }
 ```
 
-## Why Use Buffers?
+## Why Use Blobs?
 
 - **Efficiency**: `Blob` fields are optimized for storing binary data. Buffers are the standard way to handle binary data in Node.js.
 - **Compatibility**: Many HarperDB features and external libraries expect binary data to be in `Buffer` or `Uint8Array` format.

package/skills/programmatic-table-requests.md

@@ -0,0 +1,185 @@
+# Programmatic Requests with HarperDB Tables
+
+In HarperDB, you can interact with your database tables programmatically using the global `tables` object. Each table defined in your schema is available as a property on this object.
+
+## Basic Usage
+
+The `tables` object provides a direct way to perform CRUD operations from within your HarperDB resources or scripts.
+
+```typescript
+const track = await tables.ExamplePeople.get(id) as ExamplePerson;
+```
+
+## Available Methods
+
+The following methods are available on each table object:
+
+### `get(idOrQuery)`
+
+Retrieves a single record by ID or multiple records matching a query.
+
+- **By ID**:
+  ```typescript
+  const person = await tables.ExamplePeople.get('person-123');
+  ```
+- **By Query**:
+  ```typescript
+  const albums = await tables.ExamplePeople.get({
+  	conditions: [{ attribute: 'name', value: 'John' }],
+  });
+  ```
+
+### `put(id, record)`
+
+Replaces an entire record with the provided data. If the record doesn't exist, it will be created.
+
+```typescript
+await tables.ExamplePeople.put('person-123', {
+	name: 'Michael Jackson',
+	tag: 'entertainer',
+});
+```
+
+### `patch(id, partialRecord)`
+
+Performs a partial update on a record. Only the specified fields will be updated.
+
+```typescript
+await tables.ExamplePeople.patch('person-123', {
+	tag: 'tragedy',
+});
+```
+
+### `delete(idOrQuery)`
+
+Deletes a record by ID or multiple records matching a query.
+
+```typescript
+await tables.ExamplePeople.delete('person-123');
+```
+
+### `post(record)`
+
+Creates a new record. Use this when you want the database to auto-generate a primary key.
+
+```typescript
+const newAlbum = await tables.ExamplePeople.post({
+	name: 'John Smith',
+	tag: 'anonymous',
+});
+```
+
+### `update(id, updates)`
+
+The `update` method is a versatile tool for modifying records. While it can perform simple partial updates like `patch`, its primary power lies in its ability to return an **Updatable Record** object for complex or atomic operations.
+
+#### Partial Update (like `patch`)
+
+When called with both an ID and an update object, it performs a partial update:
+
+```typescript
+await tables.ExamplePeople.update('person-123', {
+	name: 'Updated Name',
+});
+```
+
+#### Getting an Updatable Record
+
+When called without an update object (only an ID), `update` returns a reference to the record that can be modified directly.
+
+```typescript
+const person = await tables.ExamplePeople.update('person-123');
+person.name = 'New Person Name';
+// Properties can be assigned directly and are tracked
+```
+
+#### Atomic Operations
+
+Updatable records provide methods for safe, atomic modifications, which are essential for avoiding race conditions during increments or decrements:
+
+- `addTo(attribute, value)`: Atomically adds to a numeric value.
+- `subtractFrom(attribute, value)`: Atomically subtracts from a numeric value.
+
+```typescript
+const stats = await tables.Stats.update('daily');
+stats.addTo('viewCount', 1);
+```
+
+#### Update without an ID or with Context
+
+Calling `update()` without an ID can be used when the target is implied by the context (e.g., inside a resource method) or when you want to get an updatable reference to a collection.
+
+```typescript
+// Inside a custom resource method
+const record = await this.update();
+record.set('status', 'processed');
+
+// Passing specific context (like a transaction)
+const person = await tables.ExamplePeople.update('person-123', null, {
+	transaction,
+});
+person.addTo('playCount', 1);
+```
+
+### `search(query)`
+
+Performs a search based on the provided query criteria. It returns an `AsyncIterable` which is efficient for streaming large result sets.
+
+```typescript
+const results = await tables.ExamplePeople.search({
+	conditions: [{ attribute: 'artist', value: 'Michael Jackson' }],
+});
+
+for await (const person of results) {
+	console.log(person.name);
+}
+```
+
+### `subscribe(query)`
+
+Subscribes to real-time changes in the table. You can provide a query to filter which changes trigger a notification.
+
+```typescript
+const subscription = await tables.ExamplePeople.subscribe({
+	conditions: [{ attribute: 'name', value: 'Thriller' }],
+});
+
+for await (const event of subscription) {
+	console.log('Record changed:', event.value);
+}
+```
+
+### `publish(id, message)`
+
+Publishes a message to a specific record or topic. This triggers any active subscriptions without necessarily persisting data to the table.
+
+```typescript
+await tables.ExamplePeople.publish('person-123', {
+	type: 'REVALIDATE',
+	timestamp: Date.now(),
+});
+```
+
+## Querying Options
+
+Many methods accept a `Query` (or `RequestTarget`) object. Common options include:
+
+- `conditions`: Array of filter conditions.
+- `limit`: Number of records to return.
+- `offset`: Number of records to skip.
+- `sort`: Attribute and direction for sorting.
+- `select`: Array of specific attributes to return.
+
+Example of a complex query:
+
+```typescript
+const recentAlbums = await tables.ExamplePeople.get({
+	conditions: [{
+		attribute: 'releaseDate',
+		comparator: 'ge',
+		value: '2020-01-01',
+	}],
+	sort: { attribute: 'releaseDate', descending: true },
+	limit: 10,
+});
+```

package/skills/serving-web-content.md

@@ -0,0 +1,82 @@
+# Serving Web Content with Harper
+
+Harper provides two primary ways to include and serve HTTP web content such as HTML, CSS, JavaScript, and React applications. These methods are mutually exclusive.
+
+## 1. Using the Static Plugin
+
+The `static` plugin is the simplest way to serve static files. It maps a directory on your filesystem to your Harper REST endpoint.
+
+### Configuration
+
+Add the `static` configuration to your `config.yaml`:
+
+```yaml
+static:
+  files: 'web/*'
+```
+
+### Usage
+
+1. Create a `web` folder in your project root.
+2. Place your static files (e.g., `index.html`, `styles.css`, `app.js`) inside the `web` folder.
+3. Your files will be accessible from your REST endpoint. For example, if Harper is running on `http://localhost:9926/`, your `index.html` will be available at that address.
+
+### Key Characteristics
+
+- **Precedence**: Static files are searched first. If a matching file is found, it is served; otherwise, Harper proceeds to check your other resource and table APIs.
+- **No Directory Listings**: Browsing the directory structure via the browser is not supported.
+- **Simple Deployment**: Ideal for pre-built applications or simple static sites.
+
+---
+
+## 2. Using the Vite Plugin
+
+The Vite plugin integrates Vite's development server directly into Harper, providing features like Hot Module Replacement (HMR) during development.
+
+### Configuration
+
+Add the Vite plugin to your `config.yaml`:
+
+```yaml
+'@harperfast/vite-plugin':
+  package: '@harperfast/vite-plugin'
+```
+
+### Setup
+
+This plugin expects a `vite.config.ts` and an `index.html` file in your project root. It handles rendering your app through Vite during development.
+
+### Package Configuration
+
+To use the Vite plugin effectively, you should configure your `package.json` with the appropriate scripts and dependencies.
+
+#### Scripts
+
+Copy these script examples to manage your development and deployment workflows:
+
+```json
+"scripts": {
+  "dev": "harper run .",
+  "build": "tsc -b && vite build",
+  "build-and-deploy": "rm -Rf deploy && npm run build && mkdir deploy && mv web deploy/ && cp -R deploy-template/* deploy/ && dotenv -- npm run deploy-web && rm -Rf deploy",
+  "deploy-web": "(cd deploy && harperdb deploy_component . project=web restart=rolling replicated=true)"
+}
+```
+
+#### Dependencies and Overrides
+
+Include the Vite plugin and other related dependencies in your `devDependencies`:
+
+```bash
+npm install --save-dev vite @harperfast/vite-plugin @vitejs/plugin-react dotenv-cli
+```
+
+### Deploying to Production
+
+Vite's HMR server is meant for development, not production. For that, the `build-and-deploy` script above builds the Vite app into a `web` folder, places the static handler, and then deploys that subdirectory as a Harper app to production.
+
+### Key Characteristics
+
+- **Development Experience**: Provides Vite's HMR for a fast development cycle.
+- **Integrated Rendering**: Automatically handles the rendering of your React/Vite app.
+- **Mutual Exclusivity**: Use this approach **instead of** the static plugin if you want Vite integration.