# @zapier/zapier-sdk-core

Core schemas and TypeScript types for the Zapier SDK API. This package provides Zod schemas for building type-safe integrations with Zapier.

## Installation

```bash
npm install @zapier/zapier-sdk-core
# or
pnpm add @zapier/zapier-sdk-core
```

## Requirements

- **Zod 4.0+** - Runtime schema validation (peer dependency)

## Usage

This package provides schemas in **two formats**:

### 1. JavaScript/TypeScript (Zod Schemas)

For consumers who want runtime validation and type safety:

```typescript
// Import from main entry point
import {
  AuthenticationSchema,
  AuthenticationItemSchema,
  type Authentication,
  type AuthenticationItem,
} from "@zapier/zapier-sdk-core";

// Or import specific schema files
import { AuthenticationSchema } from "@zapier/zapier-sdk-core/v0/schemas/authentications";

// Use Zod schema for validation
const result = AuthenticationSchema.parse(data);

// Use TypeScript type for type safety
const myAuth: Authentication = {
  id: 12345,
  date: "2023-01-01T00:00:00Z",
  account_id: 123,
  selected_api: "SlackCLIAPI@1.0.0",
  is_invite_only: false,
  is_private: true,
  shared_with_all: false,
  label: "My Slack Account",
};
```

### 2. OpenAPI Specification

For SDK generation, documentation tools, and non-TypeScript consumers:

```typescript
// Node.js / TypeScript
import { readFileSync } from "fs";
import { resolve } from "path";

const specPath = resolve(
  require.resolve("@zapier/zapier-sdk-core/package.json"),
  "../openapi.yaml",
);
const spec = readFileSync(specPath, "utf-8");

// Or with a YAML parser
import yaml from "yaml";
const openapiSpec = yaml.parse(spec);
```

The OpenAPI spec is auto-generated from the Zod schemas and kept in sync via the `prepublishOnly` script.

## Available Schemas

### Main Entry Point

- `AuthenticationSchema` - Raw authentication data from API
- `AuthenticationItemSchema` - Normalized authentication with computed fields
- `ErrorCodeSchema`, `ErrorSourceSchema`, `ErrorObjectSchema`, `ErrorsResponseSchema` - Error handling

### Direct Imports

- `@zapier/zapier-sdk-core/v0/schemas/authentications` - Authentication schemas
- `@zapier/zapier-sdk-core/v0/schemas/errors` - Error schemas
- `@zapier/zapier-sdk-core/v0/common/responses` - Common response utilities

## Package Structure

This package is designed for minimal dependencies:

- **Runtime:** Only Zod is required
- **Compiled output:** Ships as JavaScript + TypeScript declarations
- **Dual format:** Both ESM and CommonJS supported
- **OpenAPI spec:** Pre-generated `openapi.yaml` included for SDK generation tools

The package contains:

- `dist/` - Compiled JavaScript + TypeScript declarations
- `openapi.yaml` - Generated OpenAPI 3.1 specification

## For SDK Developers

This package is consumed by `@zapier/zapier-sdk` and is the source of truth for API schemas.

**Key use cases:**

- **TypeScript SDK**: Import Zod schemas directly for runtime validation
- **Multi-language SDK generation**: Use `openapi.yaml` with code generators (openapi-generator, Kiota, etc.)
- **Documentation**: Use `openapi.yaml` with tools like Redoc, Stoplight, Swagger UI

The OpenAPI spec is automatically generated from TypeScript Zod schemas, ensuring both formats stay in sync.

## License

Copyright (c) Zapier, Inc.

By using this package, you agree to the [Zapier Terms of Service](https://zapier.com/tos). See the LICENSE file for full details.

## Support

This is a pre-release version (0.x). APIs may change before 1.0.0 release.