SDK Reference

import type {
  ConnectorDefinition,
  ActionDefinition,
  ActionContext,
  ActionResult,
  ParamDefinition,
} from '@feelr/connector-sdk'
 
import { FeelrError } from '@feelr/connector-sdk'
import type { ErrorCode, Hint, FeelrErrorOptions } from '@feelr/connector-sdk'

interface ConnectorDefinition {
  name: string
  display_name: string
  version: string
  auth_type: 'oauth2' | 'api_key' | 'bearer_token' | 'none'
  actions: Record<string, ActionDefinition>
}

import type { ConnectorDefinition } from '@feelr/connector-sdk'
import { tasksList } from './actions/tasks-list'
import { tasksCreate } from './actions/tasks-create'
 
export const todoistConnector: ConnectorDefinition = {
  name: 'todoist',
  display_name: 'Todoist',
  version: '1.0.0',
  auth_type: 'api_key',
  actions: {
    'tasks.list': tasksList,
    'tasks.create': tasksCreate,
  },
}

interface ActionDefinition {
  name: string
  description: string
  params: ParamDefinition[]
  returns: 'list' | 'single'
  handler: (ctx: ActionContext) => Promise<ActionResult>
}

import type { ActionDefinition, ActionContext, ActionResult } from '@feelr/connector-sdk'
 
export const tasksList: ActionDefinition = {
  name: 'tasks.list',
  description: 'Lists tasks with optional filtering by project. Accepts project_id and per_page params. Returns array of { id, content, is_completed, created_at } objects.',
  params: [
    { name: 'project_id', type: 'string', required: false, description: 'Filter by project ID' },
    { name: 'per_page', type: 'number', required: false, description: 'Results per page (max 100)', default: 20 },
  ],
  returns: 'list',
  handler: async (ctx: ActionContext): Promise<ActionResult> => {
    // Implementation here
  },
}

interface ActionContext {
  params: Record<string, unknown>
  fetch: typeof globalThis.fetch
  credential?: string
  cursor?: string
}

interface ActionResult {
  data: Record<string, unknown>[] | Record<string, unknown>
  meta?: {
    cursor?: string
    has_more?: boolean
    total_count?: number
  }
  raw?: unknown
}

return {
  data: [
    { id: '1', content: 'Buy groceries', is_completed: false, created_at: '2024-01-15' },
    { id: '2', content: 'Write docs', is_completed: true, created_at: '2024-01-16' },
  ],
  meta: {
    has_more: true,
    cursor: 'eyJpZCI6Mn0=',
    total_count: 42,
  },
  raw: upstreamResponse,
}

return {
  data: { id: '1', content: 'Buy groceries', is_completed: false, created_at: '2024-01-15' },
  raw: upstreamResponse,
}

interface ParamDefinition {
  name: string
  type: 'string' | 'number' | 'boolean'
  required: boolean
  description: string
  default?: string | number | boolean
}

params: [
  { name: 'owner', type: 'string', required: true, description: 'Repository owner (user or org)' },
  { name: 'state', type: 'string', required: false, description: 'Filter: open, closed, all', default: 'open' },
  { name: 'per_page', type: 'number', required: false, description: 'Results per page (max 100)', default: 20 },
  { name: 'include_archived', type: 'boolean', required: false, description: 'Include archived items', default: false },
]

class FeelrError extends Error {
  readonly code: ErrorCode
  readonly hint: Hint
  readonly status: FeelrHttpStatus
  readonly detail?: string
 
  constructor(code: ErrorCode, options: FeelrErrorOptions)
}

type ErrorCode =
  | 'CONNECTOR_NOT_FOUND'
  | 'ACTION_NOT_FOUND'
  | 'VALIDATION_ERROR'
  | 'AUTH_REQUIRED'
  | 'AUTH_INVALID'
  | 'FORBIDDEN'
  | 'UPSTREAM_ERROR'
  | 'UPSTREAM_TIMEOUT'
  | 'RATE_LIMITED'
  | 'INTERNAL_ERROR'
  | 'NOT_FOUND'
  | 'CREDENTIAL_EXPIRED'
  | 'ADMIN_AUTH_REQUIRED'
  | 'ADMIN_AUTH_INVALID'
  | 'PLAN_QUOTA_EXCEEDED'

type Hint = 'retry' | 'auth' | 'abort'

interface FeelrErrorOptions {
  message: string
  hint: Hint
  status: FeelrHttpStatus
  detail?: string
}

import { FeelrError } from '@feelr/connector-sdk'
 
// Resource not found
throw new FeelrError('NOT_FOUND', {
  message: 'Task not found',
  hint: 'abort',
  status: 404,
  detail: `No task with ID ${taskId}`,
})
 
// Rate limited
throw new FeelrError('RATE_LIMITED', {
  message: 'Rate limit exceeded',
  hint: 'retry',
  status: 429,
  detail: 'Retry after 60 seconds',
})
 
// Upstream error
throw new FeelrError('UPSTREAM_ERROR', {
  message: 'Todoist API returned an error',
  hint: 'retry',
  status: 502,
  detail: upstreamErrorBody,
})
 
// Invalid parameters
throw new FeelrError('VALIDATION_ERROR', {
  message: 'Invalid project_id format',
  hint: 'abort',
  status: 400,
  detail: 'project_id must be a numeric string',
})