Skip to content
← Public packages

@kody/origin

Inspect Cursor Origin repositories, pull requests, and installations with a saved Origin App.

FollowFork

Files

types.ts

161 lines · 4.2 KB · TypeScript
/**
 * @fileoverview Shared Origin types: `OriginAccountInput`, `OriginMutationInput`, `OriginRequestParams`,
 * `OriginRequestResult`, `OriginRepoSummary`, `OriginInstallation`, and related shapes.
 * Import from `kody:@kody/origin/types` when typing Origin helpers. Default export is `ORIGIN_API_BASE_URL`.
 *
 * @example
 * import { ORIGIN_API_BASE_URL, type OriginAccountInput } from 'kody:@kody/origin/types'
 * const account: OriginAccountInput = { account: 'work' }
 */

/**
 * Shared Origin types for this package: `OriginAccountInput`, `OriginMutationInput`,
 * `OriginRequestParams`, `OriginRequestResult`, `OriginRepoSummary`, `OriginInstallation`, and related shapes.
 * Import from `kody:@kody/origin/types` when typing Origin helpers without pulling runtime clients.
 * The default export is `ORIGIN_API_BASE_URL`.
 *
 * @example
 * import { ORIGIN_API_BASE_URL, type OriginAccountInput } from 'kody:@kody/origin/types'
 * const account: OriginAccountInput = { account: 'work' }
 * // ORIGIN_API_BASE_URL === 'https://api.cursor.com/v1/origin'
 */

/**
 * Shared Origin types for this package: `OriginAccountInput`, `OriginMutationInput`,
 * `OriginRequestParams`, `OriginRequestResult`, `OriginRepoSummary`, `OriginInstallation`, and related shapes.
 * Import from `kody:@kody/origin/types` when typing Origin helpers without pulling runtime clients.
 *
 * @returns Catalog of exported type names for agent discovery.
 *
 * @example
 * import types from 'kody:@kody/origin/types'
 * const catalog = await types()
 */
export default async function typesOverview() {
	return {
		types: [
			'OriginAccountInput',
			'OriginMutationInput',
			'OriginRequestParams',
			'OriginRequestResult',
			'OriginOwner',
			'OriginRepoSummary',
			'OriginInstallation',
		],
	}
}

export const ORIGIN_API_BASE_URL = 'https://api.cursor.com/v1/origin'

export type OriginAuthMode = 'app' | 'installation'

export type OriginQuery = Record<
	string,
	string | number | boolean | null | undefined
>

export type OriginAccountInput = {
	/** Account namespace. Alias of `integrationName`. Default `origin`. */
	account?: string
	/** Account namespace used to pick secret and storage keys. Default `origin`. */
	integrationName?: string
	/** Origin App private-key secret name. Default `originAppPrivateKey` or `originAppPrivateKey-<account>`. */
	secretName?: string
	/** Origin App id (`app_01…`). Overrides package storage for this call. */
	appId?: string
	/** Origin installation id (`i_01…`). Overrides package storage for this call. */
	installationId?: string
}

export type OriginMutationInput = {
	/** Preview a write without calling Origin. */
	dryRun?: boolean
	/** Perform the live write. Required when `dryRun` is not set. */
	confirm?: boolean
}

export type OriginRequestParams = OriginAccountInput &
	OriginMutationInput & {
		path: string
		method?: string
		query?: OriginQuery
		body?: unknown
		auth?: OriginAuthMode
		scopes?: Array<string>
	}

export type OriginRequestResult = {
	ok: boolean
	status: number
	body: unknown
	rateLimit: {
		limit: string | null
		remaining: string | null
		used: string | null
		reset: string | null
	}
	dryRun?: true
}

export type OriginOwner = {
	slug: string
	id: string
	type: string | null
}

export type OriginRepoSummary = {
	id: string
	name: string
	fullName: string | null
	owner: OriginOwner | null
	defaultBranch: string | null
	cloneUrl: string | null
	mirror: {
		source: string | null
		status: string | null
	} | null
}

export type OriginInstallation = {
	id: string
	appId: string | null
	target: OriginOwner | null
	repoSelectionMode: string | null
	scopes: Array<string>
}

export type OriginPullSummary = {
	number: string | number | null
	title: string | null
	state: string | null
	draft: boolean | null
	merged: boolean | null
	head: string | null
	base: string | null
	url: string | null
}

export type OriginRateLimit = {
	limit: number | null
	remaining: number | null
	used: number | null
	reset: number | null
}

export type OriginResolvedAccount = {
	account: string
	secretName: string
	appIdKey: string
	installationIdKey: string
}

export type OriginAuthLaneInfo = {
	lane: 'origin-app'
	default: boolean
	account: string
	secretName: string
	secretSetupUrl: string
	useWhen: string
	avoidWhen: string
	mutationGuidance: string
}