npm package: @openpets/hackernews
Description: Fetch top stories, search articles, get detailed comments, and look up user profiles from Hacker News
Latest version: 1.0.2

# Pet Plugin Template

A minimal template for creating OpenCode plugins. Copy this folder and customize it to build your own plugin.

## Quick Start

### 1. Copy This Template

```bash
# From pets directory
cp -r _TEMPLATE_ my-plugin
cd my-plugin
```

### 2. Customize

Edit these files:

**package.json:**
- Change `name` to `openpets/my-plugin`
- Update `description`
- Add your environment variables in `envVariables`
- Add example queries in `queries`

**index.ts:**
- Rename `TemplatePlugin` to `MyPlugin`
- Add your tools to the `tools` array
- Implement your logic in the `execute` functions

**opencode.json:**
- Update if needed (usually no changes required)

### 3. Test

```bash
npm install
npm run quickstart
```

## Basic Structure

```typescript
export const MyPlugin = async () => {
  const tools: ToolDefinition[] = [
    {
      name: "my-tool",
      description: "What this tool does",
      schema: z.object({
        param: z.string().describe("Parameter description")
      }),
      execute: async (args) => {
        // Your logic here
        return JSON.stringify({
          success: true,
          data: "result"
        })
      }
    }
  ]

  return createPlugin(tools)
}
```

## Adding Multiple Tools

Just add more tool definitions to the array:

```typescript
const tools: ToolDefinition[] = [
  {
    name: "tool-one",
    description: "First tool",
    schema: z.object({ /* ... */ }),
    execute: async (args) => { /* ... */ }
  },
  {
    name: "tool-two",
    description: "Second tool",
    schema: z.object({ /* ... */ }),
    execute: async (args) => { /* ... */ }
  }
]
```

## Using Utilities

Import utilities from `@/utils/`:

```typescript
// Example: Using Google Maps
const { GoogleMapsAPI } = await import("@/utils/google-maps")
const maps = new GoogleMapsAPI({ apiKey: process.env.GOOGLE_MAPS_API_KEY })
const result = await maps.geocode("New York")

// Example: Using FAL AI
const { createFalClient } = await import("@/utils/fal")
const fal = createFalClient()
```

## Environment Variables

Add to `package.json`:

```json
{
  "envVariables": {
    "required": [
      {
        "name": "MY_API_KEY",
        "description": "API key for my service",
        "provider": "My Service",
        "priority": 1
      }
    ],
    "optional": [
      {
        "name": "MY_CONFIG",
        "description": "Optional configuration",
        "provider": "Configuration",
        "priority": 2
      }
    ]
  }
}
```

Access in code:

```typescript
const apiKey = process.env.MY_API_KEY
```

## Schema Validation with Zod

Define your parameters with type safety:

```typescript
schema: z.object({
  // String
  name: z.string().describe("User name"),

  // Optional string with default
  greeting: z.string().optional().default("Hello").describe("Greeting"),

  // Number
  age: z.number().describe("User age"),

  // Enum
  type: z.enum(["user", "admin"]).describe("User type"),

  // Boolean
  active: z.boolean().describe("Is active"),

  // Array
  tags: z.array(z.string()).describe("Tags list")
})
```

## Return Format

Always return JSON string:

```typescript
// Success
return JSON.stringify({
  success: true,
  data: yourData,
  message: "Operation completed"
})

// Error
return JSON.stringify({
  success: false,
  error: "Error message"
})
```

## That's It!

You now have everything you need to build your own plugin. Keep it simple and add complexity as needed.

For more examples, check out other plugins in the `pets/` directory.