create-harper 1.2.2 → 1.3.1

package/template-vanilla/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/template-vanilla/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/template-vanilla/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.

package/template-vanilla/skills/deploying-to-harper-fabric.md

@@ -1,20 +0,0 @@
-# Deploying to Harper Fabric
-
-To deploy your application to Harper Fabric, follow these steps:
-
-1. **Sign up**: Create an account at [https://fabric.harper.fast](https://fabric.harper.fast) and create a cluster.
-
-2. **Configure Environment**: Add your credentials and cluster URL to your `.env` file:
-   ```bash
-   # Deployments
-   CLI_TARGET_USERNAME='YOUR_CLUSTER_USERNAME'
-   CLI_TARGET_PASSWORD='YOUR_CLUSTER_PASSWORD'
-   CLI_TARGET='YOUR_FABRIC.HARPER.FAST_CLUSTER_URL_HERE'
-   ```
-
-3. **Deploy Locally**: Run the following command to deploy from your local environment:
-   ```bash
-   npm run deploy
-   ```
-
-4. **Set up CI/CD**: Customize the included `.github/workflow/deploy.yaml` file and define your secrets in your GitHub repository's action settings to enable continuous deployment.

package/template-vanilla/skills/extending-tables.md

@@ -1,70 +0,0 @@
-# Extending Table Resources in Harper
-
-In Harper, when you define a table in GraphQL and export it, you can extend the automatically generated resource class to add custom logic, validation, or hooks to standard CRUD operations.
-
-## Do you need to extend tables?
-
-Exported tables have [automatic APIs](./automatic-apis.md) as a part of them. These APIs may be sufficient for what you need.
-
-## How to Extend a Table Resource
-
-1. Identify the table you want to extend (e.g., `ExamplePeople`).
-2. Create a TypeScript file in your `resources/` folder.
-3. Export a class that extends `tables.YourTableName`.
-4. Override the desired methods (e.g., `post`, `get`, `put`, `patch`, `delete`).
-
-### Example: `resources/examplePeople.ts`
-
-```typescript
-import { type RequestTargetOrId, tables } from 'harperdb';
-
-export interface ExamplePerson {
-	id: string;
-	name: string;
-	tag: string;
-}
-
-// Extend the automatically generated table resource
-export class ExamplePeople extends tables.ExamplePeople<ExamplePerson> {
-	// Override the custom POST handler
-	async post(target: RequestTargetOrId, newRecord: Omit<ExamplePerson, 'id'>) {
-		// Add custom validation or transformation logic
-		if (!newRecord.name) {
-			throw new Error('Name is required');
-		}
-
-		console.log(`Adding new person: ${newRecord.name}`);
-
-		// Call the super method to perform the actual insertion
-		return super.post(target, newRecord);
-	}
-
-	// Override the custom GET handler
-	async get(target: RequestTargetOrId) {
-		const record = await super.get(target);
-		// Modify the record before returning if necessary
-		return record;
-	}
-}
-```
-
-## Why Extend Tables?
-
-- **Validation**: Ensure data meets specific criteria before it's saved to the database.
-- **Side Effects**: Send an email, trigger a webhook, or log an event when a record is created or updated.
-- **Data Transformation**: Format or enrich data before it's returned to the client.
-- **Access Control**: Add custom logic to determine if a user has permission to access or modify a specific record.
-
-## Important Note
-
-When you extend a table resource, Harper 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/template-vanilla/skills/handling-binary-data.md

@@ -1,67 +0,0 @@
-# Handling Binary Data in Harper
-
-When working with binary data (such as images or audio files) in Harper, you often receive this data as base64-encoded strings through JSON REST APIs. To store this data efficiently in a `Blob` field, you should convert it to a `Buffer`.
-
-## Storing Base64 Strings as Buffers
-
-In a custom resource or a table resource override, you can intercept the incoming record and convert base64 strings to buffers before saving them to the database.
-
-### Example
-
-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';
-
-export class MyResource extends Resource {
-	async post(target: RequestTargetOrId, record: any) {
-		if (record.data) {
-			// Convert base64-encoded string to a Buffer
-			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);
-	}
-}
-```
-
-## Responding with Binary Data
-
-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: Responding with a JPEG File
-
-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';
-
-export class TrackResource extends Resource {
-	async get(target: RequestTargetOrId) {
-		const id = (target as RequestTarget)?.id;
-		if (!id) {
-			return super.get(target);
-		}
-		const thumbnail = await super.get(target);
-		if (thumbnail?.data) {
-			return {
-				status: 200,
-				headers: {
-					'Content-Type': 'image/jpeg',
-					'Content-Disposition': `inline; filename="${thumbnail.name}.jpg"`,
-				},
-				body: thumbnail.data,
-			};
-		}
-		return thumbnail;
-	}
-}
-```
-
-## 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 Harper features and external libraries expect binary data to be in `Buffer` or `Uint8Array` format.
-- **Storage**: Storing data as binary is more compact than storing it as a base64-encoded string.