@jaypie/mcp 0.2.2 → 0.2.4

package/dist/llm.d.ts

@@ -0,0 +1,41 @@
+/**
+ * LLM debugging utilities for inspecting raw provider responses
+ */
+export type LlmProvider = "anthropic" | "gemini" | "openai" | "openrouter";
+export interface LlmDebugCallParams {
+    provider: LlmProvider;
+    model?: string;
+    message: string;
+}
+export interface LlmDebugCallResult {
+    success: boolean;
+    provider: string;
+    model: string;
+    content?: string;
+    reasoning?: string[];
+    reasoningTokens?: number;
+    history?: unknown[];
+    rawResponses?: unknown[];
+    usage?: unknown[];
+    error?: string;
+}
+interface Logger {
+    info: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+export declare const REASONING_MODELS: Record<string, string>;
+/**
+ * Make a debug LLM call and return the raw response data for inspection
+ */
+export declare function debugLlmCall(params: LlmDebugCallParams, log: Logger): Promise<LlmDebugCallResult>;
+/**
+ * List available providers and their default/reasoning models
+ */
+export declare function listLlmProviders(): {
+    providers: Array<{
+        name: LlmProvider;
+        defaultModel: string;
+        reasoningModels: string[];
+    }>;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaypie/mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Jaypie MCP",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
     "prompts"
   ],
   "scripts": {
-    "build": "rollup --config",
+    "build": "rollup --config && chmod +x dist/index.js",
     "format": "eslint . --fix",
     "lint": "eslint .",
     "prepare": "npm run build",
@@ -34,6 +34,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@jaypie/llm": "^1.2.2",
     "@modelcontextprotocol/sdk": "^1.17.0",
     "commander": "^14.0.0",
     "gray-matter": "^4.0.3",

package/prompts/Jaypie_CDK_Constructs_and_Patterns.md

@@ -100,6 +100,57 @@ new JaypieExpressLambda(this, "ExpressApp", {
 
 Preconfigured with API-optimized timeouts and role tags.
 
+### Streaming Lambda Functions
+
+Enable Lambda Response Streaming via Function URLs for real-time SSE responses:
+
+```typescript
+import { FunctionUrlAuthType, InvokeMode } from "aws-cdk-lib/aws-lambda";
+
+const streamingLambda = new JaypieLambda(this, "StreamingFunction", {
+  code: "dist",
+  handler: "stream.handler",
+  timeout: Duration.minutes(5), // Longer timeout for streaming
+});
+
+// Add Function URL with streaming enabled
+const functionUrl = streamingLambda.addFunctionUrl({
+  authType: FunctionUrlAuthType.NONE,     // Public access
+  // authType: FunctionUrlAuthType.AWS_IAM, // IAM authentication
+  invokeMode: InvokeMode.RESPONSE_STREAM, // Enable streaming
+});
+
+// Output the URL
+new cdk.CfnOutput(this, "StreamingUrl", {
+  value: functionUrl.url,
+});
+```
+
+Features:
+- `RESPONSE_STREAM` invoke mode enables real-time streaming
+- Works with `lambdaStreamHandler` from `@jaypie/lambda`
+- Use `FunctionUrlAuthType.AWS_IAM` for authenticated endpoints
+- Combine with API Gateway for custom domains via `JaypieApiGateway`
+
+For Express-based streaming with custom domains:
+```typescript
+// Express app with streaming routes
+const expressLambda = new JaypieExpressLambda(this, "ExpressStream", {
+  code: "dist",
+  handler: "app.handler",
+  timeout: Duration.minutes(5),
+});
+
+// API Gateway handles the domain routing
+new JaypieApiGateway(this, "Api", {
+  handler: expressLambda,
+  host: "api.example.com",
+  zone: "example.com",
+});
+```
+
+Note: API Gateway has a 29-second timeout limit. For longer streaming operations, use Function URLs directly.
+
 ### Stack Types
 
 Use specialized stacks for different purposes:

package/prompts/Jaypie_DynamoDB_Package.md

@@ -0,0 +1,547 @@
+---
+description: Complete guide to @jaypie/dynamodb single-table design utilities including GSI patterns, key builders, entity operations, and query functions
+globs: packages/dynamodb/**
+---
+
+# Jaypie DynamoDB Package
+
+Jaypie provides DynamoDB single-table design utilities through `@jaypie/dynamodb`. The package implements a five-GSI pattern for hierarchical data with named access patterns (not gsi1, gsi2, etc.).
+
+## Installation
+
+```bash
+npm install @jaypie/dynamodb
+```
+
+## Core Concepts
+
+### Single-Table Design
+
+All entities share a single DynamoDB table with:
+- **Primary Key**: `model` (partition) + `id` (sort)
+- **Five GSIs**: All use `sequence` as sort key for chronological ordering
+
+### Organizational Unit (OU)
+
+The `ou` field creates hierarchical relationships:
+- Root entities: `ou = "@"` (APEX constant)
+- Child entities: `ou = "{parent.model}#{parent.id}"`
+
+### GSI Pattern
+
+| GSI Name | Partition Key | Use Case |
+|----------|---------------|----------|
+| `indexOu` | `{ou}#{model}` | List all entities under a parent |
+| `indexAlias` | `{ou}#{model}#{alias}` | Human-friendly slug lookup |
+| `indexClass` | `{ou}#{model}#{class}` | Category filtering |
+| `indexType` | `{ou}#{model}#{type}` | Type filtering |
+| `indexXid` | `{ou}#{model}#{xid}` | External system ID lookup |
+
+## Client Initialization
+
+Initialize once at application startup:
+
+```typescript
+import { initClient } from "@jaypie/dynamodb";
+
+initClient({
+  tableName: process.env.DYNAMODB_TABLE_NAME,
+  region: process.env.AWS_REGION,           // Optional, defaults to us-east-1
+  endpoint: process.env.DYNAMODB_ENDPOINT,  // Optional, for local dev
+});
+```
+
+For local development with DynamoDB Local:
+
+```typescript
+initClient({
+  tableName: "local-table",
+  endpoint: "http://127.0.0.1:8100",
+  // Credentials auto-detected for localhost endpoints
+});
+```
+
+## FabricEntity Interface
+
+All entities must implement `FabricEntity`:
+
+```typescript
+import type { FabricEntity } from "@jaypie/dynamodb";
+
+interface MyRecord extends FabricEntity {
+  // Primary Key (required)
+  model: string;      // e.g., "record"
+  id: string;         // UUID
+
+  // Required fields
+  name: string;
+  ou: string;         // APEX or hierarchical
+  sequence: number;   // Date.now()
+
+  // Timestamps (ISO 8601)
+  createdAt: string;
+  updatedAt: string;
+  archivedAt?: string; // Set by archiveEntity
+  deletedAt?: string;  // Set by deleteEntity
+
+  // Optional - trigger GSI population
+  alias?: string;     // Human-friendly slug
+  class?: string;     // Category
+  type?: string;      // Type classification
+  xid?: string;       // External ID
+}
+```
+
+## Entity Operations
+
+### Creating Entities
+
+Use `putEntity` to create or replace entities. GSI keys are auto-populated:
+
+```typescript
+import { APEX, putEntity } from "@jaypie/dynamodb";
+
+const now = new Date().toISOString();
+
+const record = await putEntity({
+  entity: {
+    model: "record",
+    id: crypto.randomUUID(),
+    name: "Daily Log",
+    ou: APEX,
+    sequence: Date.now(),
+    alias: "2026-01-07",    // Optional
+    class: "memory",        // Optional
+    createdAt: now,
+    updatedAt: now,
+  },
+});
+
+// Result includes auto-populated indexes:
+// indexOu: "@#record"
+// indexAlias: "@#record#2026-01-07"
+// indexClass: "@#record#memory"
+```
+
+### Getting Entities
+
+```typescript
+import { getEntity } from "@jaypie/dynamodb";
+
+const record = await getEntity({ id: "123", model: "record" });
+// Returns entity or null
+```
+
+### Updating Entities
+
+Use `updateEntity` to update. Automatically sets `updatedAt` and re-indexes:
+
+```typescript
+import { updateEntity } from "@jaypie/dynamodb";
+
+const updated = await updateEntity({
+  entity: {
+    ...existingRecord,
+    name: "Updated Name",
+    alias: "new-alias",
+  },
+});
+// updatedAt is set automatically
+// indexAlias is re-calculated
+```
+
+### Soft Delete
+
+Use `deleteEntity` for soft delete (sets `deletedAt`):
+
+```typescript
+import { deleteEntity } from "@jaypie/dynamodb";
+
+await deleteEntity({ id: "123", model: "record" });
+// Sets deletedAt and updatedAt timestamps
+// Entity excluded from queries by default
+```
+
+### Archive
+
+Use `archiveEntity` for archiving (sets `archivedAt`):
+
+```typescript
+import { archiveEntity } from "@jaypie/dynamodb";
+
+await archiveEntity({ id: "123", model: "record" });
+// Sets archivedAt and updatedAt timestamps
+// Entity excluded from queries by default
+```
+
+### Hard Delete
+
+Use `destroyEntity` to permanently remove:
+
+```typescript
+import { destroyEntity } from "@jaypie/dynamodb";
+
+await destroyEntity({ id: "123", model: "record" });
+// Permanently removes from table
+```
+
+### Hierarchical Entities
+
+Use `calculateOu` to derive OU from parent:
+
+```typescript
+import { calculateOu, putEntity, queryByOu } from "@jaypie/dynamodb";
+
+// Parent reference
+const chat = { model: "chat", id: "abc-123" };
+
+// Calculate child OU
+const messageOu = calculateOu(chat); // "chat#abc-123"
+
+// Create child entity
+const message = await putEntity({
+  entity: {
+    model: "message",
+    id: crypto.randomUUID(),
+    name: "First message",
+    ou: messageOu,
+    sequence: Date.now(),
+    createdAt: now,
+    updatedAt: now,
+  },
+});
+// indexOu: "chat#abc-123#message"
+
+// Query all messages in chat
+const { items } = await queryByOu({ model: "message", ou: messageOu });
+```
+
+## Query Functions
+
+All queries use object parameters and filter soft-deleted and archived records by default.
+
+### queryByOu - List by Parent
+
+List all entities of a model under a parent:
+
+```typescript
+import { APEX, queryByOu } from "@jaypie/dynamodb";
+
+// Root-level records
+const { items, lastEvaluatedKey } = await queryByOu({
+  model: "record",
+  ou: APEX,
+});
+
+// Messages under a chat
+const { items: messages } = await queryByOu({
+  model: "message",
+  ou: "chat#abc-123",
+});
+```
+
+### queryByAlias - Human-Friendly Lookup
+
+Single entity lookup by slug:
+
+```typescript
+import { APEX, queryByAlias } from "@jaypie/dynamodb";
+
+const record = await queryByAlias({
+  alias: "2026-01-07",
+  model: "record",
+  ou: APEX,
+});
+// Returns entity or null
+```
+
+### queryByClass / queryByType - Category Filtering
+
+```typescript
+import { APEX, queryByClass, queryByType } from "@jaypie/dynamodb";
+
+// All memory records
+const { items } = await queryByClass({
+  model: "record",
+  ou: APEX,
+  recordClass: "memory",
+});
+
+// All note-type records
+const { items: notes } = await queryByType({
+  model: "record",
+  ou: APEX,
+  type: "note",
+});
+```
+
+### queryByXid - External ID Lookup
+
+Single entity lookup by external system ID:
+
+```typescript
+import { APEX, queryByXid } from "@jaypie/dynamodb";
+
+const record = await queryByXid({
+  model: "record",
+  ou: APEX,
+  xid: "ext-12345",
+});
+// Returns entity or null
+```
+
+### Query Options
+
+```typescript
+import type { BaseQueryOptions } from "@jaypie/dynamodb";
+
+const result = await queryByOu({
+  model: "record",
+  ou: APEX,
+  // BaseQueryOptions:
+  limit: 25,                // Max items to return
+  ascending: true,          // Oldest first (default: false = newest first)
+  includeDeleted: true,     // Include soft-deleted records
+  includeArchived: true,    // Include archived records
+  startKey: lastEvaluatedKey, // Pagination cursor
+});
+```
+
+### Pagination
+
+```typescript
+import { APEX, queryByOu } from "@jaypie/dynamodb";
+
+let startKey: Record<string, unknown> | undefined;
+const allItems: FabricEntity[] = [];
+
+do {
+  const { items, lastEvaluatedKey } = await queryByOu({
+    model: "record",
+    ou: APEX,
+    limit: 100,
+    startKey,
+  });
+  allItems.push(...items);
+  startKey = lastEvaluatedKey;
+} while (startKey);
+```
+
+## Key Builder Functions
+
+Use `indexEntity` to auto-populate GSI keys on an entity:
+
+```typescript
+import { indexEntity } from "@jaypie/dynamodb";
+
+const indexed = indexEntity({
+  model: "record",
+  id: "123",
+  ou: "@",
+  alias: "my-alias",
+  // ...
+});
+// indexOu: "@#record"
+// indexAlias: "@#record#my-alias"
+```
+
+Use individual key builders for manual key construction:
+
+```typescript
+import {
+  buildIndexOu,
+  buildIndexAlias,
+  buildIndexClass,
+  buildIndexType,
+  buildIndexXid,
+} from "@jaypie/dynamodb";
+
+buildIndexOu("@", "record");                    // "@#record"
+buildIndexAlias("@", "record", "my-alias");     // "@#record#my-alias"
+buildIndexClass("@", "record", "memory");       // "@#record#memory"
+buildIndexType("@", "record", "note");          // "@#record#note"
+buildIndexXid("@", "record", "ext-123");        // "@#record#ext-123"
+```
+
+## Constants
+
+```typescript
+import {
+  APEX,           // "@" - Root-level marker
+  SEPARATOR,      // "#" - Composite key separator
+  INDEX_OU,       // "indexOu"
+  INDEX_ALIAS,    // "indexAlias"
+  INDEX_CLASS,    // "indexClass"
+  INDEX_TYPE,     // "indexType"
+  INDEX_XID,      // "indexXid"
+} from "@jaypie/dynamodb";
+```
+
+## Table Schema (CloudFormation/CDK Reference)
+
+```yaml
+AttributeDefinitions:
+  - AttributeName: model
+    AttributeType: S
+  - AttributeName: id
+    AttributeType: S
+  - AttributeName: indexOu
+    AttributeType: S
+  - AttributeName: indexAlias
+    AttributeType: S
+  - AttributeName: indexClass
+    AttributeType: S
+  - AttributeName: indexType
+    AttributeType: S
+  - AttributeName: indexXid
+    AttributeType: S
+  - AttributeName: sequence
+    AttributeType: N
+
+KeySchema:
+  - AttributeName: model
+    KeyType: HASH
+  - AttributeName: id
+    KeyType: RANGE
+
+GlobalSecondaryIndexes:
+  - IndexName: indexOu
+    KeySchema:
+      - AttributeName: indexOu
+        KeyType: HASH
+      - AttributeName: sequence
+        KeyType: RANGE
+    Projection:
+      ProjectionType: ALL
+  # Repeat for indexAlias, indexClass, indexType, indexXid
+```
+
+## Error Handling
+
+Functions throw `ConfigurationError` if client is not initialized:
+
+```typescript
+import { getDocClient } from "@jaypie/dynamodb";
+
+try {
+  const client = getDocClient();
+} catch (error) {
+  // ConfigurationError: DynamoDB client not initialized. Call initClient() first.
+}
+```
+
+## Testing
+
+Mock implementations in `@jaypie/testkit`:
+
+```typescript
+import { vi } from "vitest";
+
+vi.mock("@jaypie/dynamodb", async () => {
+  const testkit = await import("@jaypie/testkit/mock");
+  return testkit;
+});
+
+// Key builders and indexEntity work correctly (delegate to real implementations)
+// Query functions return empty results by default
+// Entity operations return sensible defaults
+
+// Customize mock behavior:
+import { queryByOu, getEntity, putEntity } from "@jaypie/testkit/mock";
+
+queryByOu.mockResolvedValue({
+  items: [{ id: "123", name: "Test" }],
+  lastEvaluatedKey: undefined,
+});
+
+getEntity.mockResolvedValue({ id: "123", model: "record", name: "Test" });
+```
+
+## Best Practices
+
+### Use putEntity, Not Direct Writes
+
+Always use `putEntity` or `updateEntity` to ensure GSI keys are auto-populated:
+
+```typescript
+// CORRECT - uses putEntity which calls indexEntity internally
+const entity = await putEntity({
+  entity: {
+    model: "record",
+    alias: "my-alias",
+    // ...
+  },
+});
+
+// WRONG - bypasses index population
+const entity = {
+  model: "record",
+  alias: "my-alias",
+  indexAlias: "@#record#my-alias", // Don't manually set index keys
+};
+```
+
+### Use indexEntity for Raw Entities
+
+If you need to prepare an entity before a batch write:
+
+```typescript
+import { indexEntity } from "@jaypie/dynamodb";
+
+// Use indexEntity to prepare entities for batch operations
+const indexed = indexEntity(myEntity);
+```
+
+### Use Meaningful Model Names
+
+Model names are part of every key. Use short, descriptive names:
+
+```typescript
+// GOOD
+{ model: "record" }
+{ model: "message" }
+{ model: "chat" }
+
+// AVOID
+{ model: "DailyLogRecord" }
+{ model: "ChatMessage_v2" }
+```
+
+### Sequence for Ordering
+
+Always set `sequence: Date.now()` for chronological ordering in GSI queries:
+
+```typescript
+const entity = await putEntity({
+  entity: {
+    // ...
+    sequence: Date.now(),  // Required for proper ordering
+  },
+});
+```
+
+### Soft Delete and Archive Patterns
+
+Use `deleteEntity` for logical deletion and `archiveEntity` for archival:
+
+```typescript
+// Soft delete - user action, can be recovered
+await deleteEntity({ id: "123", model: "record" });
+
+// Archive - system action, long-term storage
+await archiveEntity({ id: "123", model: "record" });
+
+// Queries exclude both by default
+const { items } = await queryByOu({ model: "record", ou: APEX });
+
+// Include if needed
+const { items: all } = await queryByOu({
+  model: "record",
+  ou: APEX,
+  includeDeleted: true,
+  includeArchived: true,
+});
+
+// Permanent deletion (use sparingly)
+await destroyEntity({ id: "123", model: "record" });
+```