jarvis/sdk/writekit.d.ts

// WriteKit Plugin SDK Type Definitions
// These types are injected into Monaco for autocomplete

// ============================================================================
// EXTISM PDK TYPES (required for compilation)
// ============================================================================

/** Host functions provided by Extism */
declare namespace Host {
  function inputString(): string;
  function inputBytes(): Uint8Array;
  function inputJSON<T>(): T;
  function outputString(s: string): void;
  function outputBytes(bytes: Uint8Array): void;
  function outputJSON<T>(obj: T): void;
  function log(msg: string): void;
}

/** Configuration access */
declare namespace Config {
  function get(key: string): string | null;
}

/** Variable storage */
declare namespace Var {
  function get(key: string): { text(): string } | null;
  function set(key: string, value: string): void;
}

/** HTTP request types */
interface HttpRequest {
  url: string;
  method: string;
  headers: Record<string, string>;
}

declare namespace Http {
  function request(req: HttpRequest, body?: Uint8Array): { status: number; body(): Uint8Array };
}

// ============================================================================
// RUNNER SDK (user-facing API)
// ============================================================================

/**
 * Runner provides all plugin capabilities
 */
declare namespace Runner {
  /** Log a message (visible in plugin logs) */
  function log(message: string): void;

  /** Make an HTTP request */
  function httpRequest(options: HttpRequestOptions): HttpResponse;

  /**
   * Access your configured secrets
   * Secret keys are dynamically typed based on your dashboard configuration
   */
  namespace secrets {
    // Dynamic: actual secret keys are injected at runtime based on user's secrets
  }
}

interface HttpRequestOptions {
  url: string;
  method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
  headers?: Record<string, string>;
  body?: string;
}

interface HttpResponse {
  status: number;
  headers: Record<string, string>;
  body: string;
}

// ============================================================================
// VALIDATION TYPES
// ============================================================================

/** Result for validation hooks (comment.validate, etc.) */
interface ValidationResult {
  allowed: boolean;
  reason?: string;
}

// ============================================================================
// EVENT TYPES
// ============================================================================

/** Event fired when a post is published */
interface PostPublishedEvent {
  post: {
    slug: string;
    title: string;
    url: string;
    excerpt: string;
    publishedAt: string;
    tags: string[];
    readingTime: number;
  };
  author: {
    name: string;
    email: string;
    avatar?: string;
  };
  blog: {
    name: string;
    url: string;
  };
}

/** Event fired when a post is updated */
interface PostUpdatedEvent {
  post: {
    slug: string;
    title: string;
    url: string;
    excerpt: string;
    publishedAt: string;
    updatedAt: string;
    tags: string[];
  };
  author: {
    name: string;
    email: string;
  };
  changes: {
    title?: { old: string; new: string };
    content?: boolean;
    tags?: { added: string[]; removed: string[] };
  };
}

/** Event fired when a comment is created */
interface CommentCreatedEvent {
  comment: {
    id: string;
    content: string;
    authorName: string;
    authorEmail: string;
    postSlug: string;
    parentId?: string;
    createdAt: string;
  };
  post: {
    slug: string;
    title: string;
    url: string;
  };
}

/** Event fired when a member subscribes */
interface MemberSubscribedEvent {
  member: {
    email: string;
    name?: string;
    subscribedAt: string;
  };
  tier: {
    name: string;
    price: number;
  };
}

/** Event fired when an asset is uploaded */
interface AssetUploadedEvent {
  id: string;
  url: string;
  contentType: string;
  size: number;
  width?: number;
  height?: number;
}

/** Event fired when analytics are synced */
interface AnalyticsSyncEvent {
  period: {
    start: string;
    end: string;
  };
  pageviews: number;
  visitors: number;
  topPages: Array<{ path: string; views: number }>;
}

// ============================================================================
// VALIDATION INPUT TYPES
// ============================================================================

/** Input for comment validation hook */
interface CommentInput {
  content: string;
  authorName: string;
  authorEmail: string;
  postSlug: string;
  parentId?: string;
}

// ============================================================================
// TRANSFORM TYPES
// ============================================================================

/** Input for content.render transform hook */
interface ContentRenderInput {
  html: string;
  post: {
    slug: string;
    title: string;
    tags: string[];
  };
}

/** Output for content.render transform hook */
interface ContentRenderOutput {
  html: string;
}

// ============================================================================
// HOOK HANDLER TYPES (for documentation)
// ============================================================================

/** Handler for post.published event */
type PostPublishedHandler = (event: PostPublishedEvent, secrets?: any) => void;

/** Handler for post.updated event */
type PostUpdatedHandler = (event: PostUpdatedEvent, secrets?: any) => void;

/** Handler for comment.validate validation */
type CommentValidateHandler = (input: CommentInput, secrets?: any) => ValidationResult;

/** Handler for comment.created event */
type CommentCreatedHandler = (event: CommentCreatedEvent, secrets?: any) => void;

/** Handler for member.subscribed event */
type MemberSubscribedHandler = (event: MemberSubscribedEvent, secrets?: any) => void;

/** Handler for content.render transform */
type ContentRenderHandler = (input: ContentRenderInput, secrets?: any) => ContentRenderOutput;

/** Handler for asset.uploaded event */
type AssetUploadedHandler = (event: AssetUploadedEvent, secrets?: any) => void;

/** Handler for analytics.sync event */
type AnalyticsSyncHandler = (event: AnalyticsSyncEvent, secrets?: any) => void;