@ofocus/sdk 0.1.0

package/dist/ofocus-sdk.d.ts

@@ -0,0 +1,608 @@
+/**
+ * Add a task to the OmniFocus inbox.
+ */
+export declare function addToInbox(title: string, options?: InboxOptions): Promise<CliOutput<OFTask>>;
+
+export declare interface AppleScriptResult<T> {
+    success: boolean;
+    data?: T;
+    error?: CliError;
+}
+
+/** Batch complete result item */
+export declare interface BatchCompleteItem {
+    taskId: string;
+    taskName: string;
+}
+
+/** Batch delete result item */
+export declare interface BatchDeleteItem {
+    taskId: string;
+}
+
+/**
+ * Result from a batch operation.
+ */
+export declare interface BatchResult<T> {
+    succeeded: T[];
+    failed: {
+        id: string;
+        error: string;
+    }[];
+    totalSucceeded: number;
+    totalFailed: number;
+}
+
+/**
+ * Build AppleScript to set a repetition rule on a task.
+ * @param taskVar - The AppleScript variable name for the task
+ * @param rule - The repetition rule to apply
+ */
+export declare function buildRepetitionRuleScript(taskVar: string, rule: RepetitionRule): string;
+
+/**
+ * Build iCalendar RRULE string from a RepetitionRule.
+ */
+export declare function buildRRule(rule: RepetitionRule): string;
+
+/**
+ * Structured error representation for CLI output.
+ */
+export declare interface CliError {
+    code: ErrorCode;
+    message: string;
+    details?: string;
+}
+
+/**
+ * Standard CLI output format for all commands.
+ */
+export declare interface CliOutput<T> {
+    success: boolean;
+    data: T | null;
+    error: CliError | null;
+}
+
+/**
+ * Metadata about a CLI command for semantic activation by AI agents.
+ */
+export declare interface CommandInfo {
+    name: string;
+    description: string;
+    usage: string;
+}
+
+/**
+ * Result from completing a task.
+ */
+export declare interface CompleteResult {
+    taskId: string;
+    taskName: string;
+    completed: boolean;
+}
+
+/**
+ * Mark a task as complete in OmniFocus.
+ */
+export declare function completeTask(taskId: string): Promise<CliOutput<CompleteResult>>;
+
+/**
+ * Complete multiple tasks in a single operation.
+ */
+export declare function completeTasks(taskIds: string[]): Promise<CliOutput<BatchResult<BatchCompleteItem>>>;
+
+/**
+ * Create a CliError with the given code and message.
+ */
+export declare function createError(code: ErrorCode, message: string, details?: string): CliError;
+
+/**
+ * Create a new folder in OmniFocus.
+ */
+export declare function createFolder(name: string, options?: CreateFolderOptions): Promise<CliOutput<OFFolder>>;
+
+/**
+ * Options for creating a folder.
+ */
+export declare interface CreateFolderOptions {
+    parentFolderId?: string | undefined;
+    parentFolderName?: string | undefined;
+}
+
+/**
+ * Create a new project in OmniFocus.
+ */
+export declare function createProject(name: string, options?: CreateProjectOptions): Promise<CliOutput<OFProject>>;
+
+/**
+ * Options for creating a project.
+ */
+export declare interface CreateProjectOptions {
+    note?: string | undefined;
+    folderId?: string | undefined;
+    folderName?: string | undefined;
+    sequential?: boolean | undefined;
+    status?: "active" | "on-hold" | undefined;
+    dueDate?: string | undefined;
+    deferDate?: string | undefined;
+}
+
+/**
+ * Create a subtask under a parent task in OmniFocus.
+ */
+export declare function createSubtask(title: string, parentTaskId: string, options?: InboxOptions): Promise<CliOutput<OFTaskWithChildren>>;
+
+/**
+ * Create a new tag in OmniFocus.
+ */
+export declare function createTag(name: string, options?: CreateTagOptions): Promise<CliOutput<OFTag>>;
+
+/**
+ * Options for creating a tag.
+ */
+export declare interface CreateTagOptions {
+    parentTagId?: string | undefined;
+    parentTagName?: string | undefined;
+}
+
+/**
+ * Result from deleting a task.
+ */
+export declare interface DeleteResult {
+    taskId: string;
+    deleted: true;
+}
+
+/**
+ * Delete a tag from OmniFocus.
+ * Note: This cannot be undone.
+ */
+export declare function deleteTag(tagId: string): Promise<CliOutput<DeleteTagResult>>;
+
+/**
+ * Result from deleting a tag.
+ */
+export declare interface DeleteTagResult {
+    tagId: string;
+    deleted: true;
+}
+
+/**
+ * Delete a task permanently from OmniFocus.
+ * Note: This cannot be undone.
+ */
+export declare function deleteTask(taskId: string): Promise<CliOutput<DeleteResult>>;
+
+/**
+ * Delete multiple tasks permanently in a single operation.
+ */
+export declare function deleteTasks(taskIds: string[]): Promise<CliOutput<BatchResult<BatchDeleteItem>>>;
+
+/**
+ * Result from dropping a task.
+ */
+export declare interface DropResult {
+    taskId: string;
+    taskName: string;
+    dropped: boolean;
+}
+
+/**
+ * Drop a task in OmniFocus (marks as dropped but keeps history).
+ */
+export declare function dropTask(taskId: string): Promise<CliOutput<DropResult>>;
+
+/**
+ * Error codes for semantic error handling.
+ */
+declare const ErrorCode: {
+    readonly TASK_NOT_FOUND: "TASK_NOT_FOUND";
+    readonly PROJECT_NOT_FOUND: "PROJECT_NOT_FOUND";
+    readonly TAG_NOT_FOUND: "TAG_NOT_FOUND";
+    readonly FOLDER_NOT_FOUND: "FOLDER_NOT_FOUND";
+    readonly PERSPECTIVE_NOT_FOUND: "PERSPECTIVE_NOT_FOUND";
+    readonly DUPLICATE_NAME: "DUPLICATE_NAME";
+    readonly OMNIFOCUS_NOT_RUNNING: "OMNIFOCUS_NOT_RUNNING";
+    readonly INVALID_DATE_FORMAT: "INVALID_DATE_FORMAT";
+    readonly INVALID_ID_FORMAT: "INVALID_ID_FORMAT";
+    readonly INVALID_REPETITION_RULE: "INVALID_REPETITION_RULE";
+    readonly APPLESCRIPT_ERROR: "APPLESCRIPT_ERROR";
+    readonly JSON_PARSE_ERROR: "JSON_PARSE_ERROR";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+};
+
+declare type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export { ErrorCode }
+export { ErrorCode as ErrorCodeType }
+
+/**
+ * Escape a string for safe use in AppleScript double-quoted strings.
+ * Handles backslashes and double quotes.
+ */
+export declare function escapeAppleScript(str: string): string;
+
+/**
+ * Create a failed CLI output with a structured error.
+ */
+export declare function failure<T = null>(error: CliError): CliOutput<T>;
+
+/**
+ * Create a failed CLI output with a simple string message.
+ * This is a convenience function that wraps the message in an UNKNOWN_ERROR.
+ */
+export declare function failureMessage<T = null>(message: string): CliOutput<T>;
+
+/**
+ * Options for querying folders.
+ */
+export declare interface FolderQueryOptions {
+    parent?: string | undefined;
+}
+
+/**
+ * Options for adding a task to the inbox.
+ */
+export declare interface InboxOptions {
+    note?: string | undefined;
+    due?: string | undefined;
+    defer?: string | undefined;
+    flag?: boolean | undefined;
+    tags?: string[] | undefined;
+    estimatedMinutes?: number | undefined;
+    repeat?: RepetitionRule | undefined;
+}
+
+/**
+ * AppleScript helper functions for JSON serialization.
+ * These must be defined at the top level (outside tell blocks).
+ */
+export declare const jsonHelpers = "\non jsonString(val)\n  if val is \"\" or val is missing value or val is \"missing value\" then\n    return \"null\"\n  else\n    return \"\\\"\" & my escapeJson(val) & \"\\\"\"\n  end if\nend jsonString\n\non jsonArray(theList)\n  if (count of theList) is 0 then\n    return \"[]\"\n  end if\n  set output to \"[\"\n  repeat with i from 1 to count of theList\n    if i > 1 then set output to output & \",\"\n    set output to output & \"\\\"\" & (my escapeJson(item i of theList)) & \"\\\"\"\n  end repeat\n  return output & \"]\"\nend jsonArray\n\non escapeJson(str)\n  set output to \"\"\n  repeat with c in characters of (str as string)\n    if c is \"\\\"\" then\n      set output to output & \"\\\\\\\"\"\n    else if c is \"\\\\\" then\n      set output to output & \"\\\\\\\\\"\n    else if c is return then\n      set output to output & \"\\\\n\"\n    else if c is linefeed then\n      set output to output & \"\\\\n\"\n    else\n      set output to output & c\n    end if\n  end repeat\n  return output\nend escapeJson\n";
+
+/**
+ * List all perspectives in OmniFocus.
+ */
+export declare function listPerspectives(): Promise<CliOutput<OFPerspective[]>>;
+
+/**
+ * Move a task to become a subtask of another task.
+ */
+export declare function moveTaskToParent(taskId: string, parentTaskId: string): Promise<CliOutput<OFTaskWithChildren>>;
+
+/**
+ * OmniFocus folder representation.
+ */
+export declare interface OFFolder {
+    id: string;
+    name: string;
+    parentId: string | null;
+    parentName: string | null;
+    projectCount: number;
+    folderCount: number;
+}
+
+/**
+ * OmniFocus perspective representation.
+ */
+export declare interface OFPerspective {
+    id: string;
+    name: string;
+    custom: boolean;
+}
+
+/**
+ * OmniFocus project representation.
+ */
+export declare interface OFProject {
+    id: string;
+    name: string;
+    note: string | null;
+    status: "active" | "on-hold" | "completed" | "dropped";
+    sequential: boolean;
+    folderId: string | null;
+    folderName: string | null;
+    taskCount: number;
+    remainingTaskCount: number;
+}
+
+/**
+ * OmniFocus tag representation.
+ */
+export declare interface OFTag {
+    id: string;
+    name: string;
+    parentId: string | null;
+    parentName: string | null;
+    availableTaskCount: number;
+}
+
+/**
+ * OmniFocus task representation.
+ */
+export declare interface OFTask {
+    id: string;
+    name: string;
+    note: string | null;
+    flagged: boolean;
+    completed: boolean;
+    dueDate: string | null;
+    deferDate: string | null;
+    completionDate: string | null;
+    projectId: string | null;
+    projectName: string | null;
+    tags: string[];
+    estimatedMinutes: number | null;
+}
+
+/**
+ * OmniFocus task with hierarchy information.
+ */
+export declare interface OFTaskWithChildren extends OFTask {
+    parentTaskId: string | null;
+    parentTaskName: string | null;
+    childTaskCount: number;
+    isActionGroup: boolean;
+}
+
+/**
+ * Build an AppleScript that tells OmniFocus to do something.
+ */
+export declare function omniFocusScript(body: string): string;
+
+/**
+ * Build an AppleScript that tells OmniFocus to do something,
+ * with JSON helper functions defined at the top level.
+ */
+export declare function omniFocusScriptWithHelpers(body: string): string;
+
+/**
+ * Parse an AppleScript error message into a structured CliError.
+ * Detects common error patterns and maps them to appropriate error codes.
+ */
+export declare function parseAppleScriptError(rawError: string): CliError;
+
+/**
+ * Options for querying a perspective.
+ */
+export declare interface PerspectiveQueryOptions {
+    limit?: number | undefined;
+}
+
+/**
+ * Options for querying projects.
+ */
+export declare interface ProjectQueryOptions {
+    folder?: string | undefined;
+    status?: "active" | "on-hold" | "completed" | "dropped" | undefined;
+    sequential?: boolean | undefined;
+}
+
+/**
+ * Query folders from OmniFocus with optional filters.
+ */
+export declare function queryFolders(options?: FolderQueryOptions): Promise<CliOutput<OFFolder[]>>;
+
+/**
+ * Query tasks from a specific perspective in OmniFocus.
+ *
+ * Note: This function retrieves tasks based on the perspective's filtering rules.
+ * Some perspectives may require UI interaction in OmniFocus to be properly evaluated.
+ * Built-in perspectives like "Flagged", "Forecast", and "Projects" work best.
+ */
+export declare function queryPerspective(name: string, options?: PerspectiveQueryOptions): Promise<CliOutput<OFTask[]>>;
+
+/**
+ * Query projects from OmniFocus with optional filters.
+ */
+export declare function queryProjects(options?: ProjectQueryOptions): Promise<CliOutput<OFProject[]>>;
+
+/**
+ * Query projects that are due for review in OmniFocus.
+ */
+export declare function queryProjectsForReview(): Promise<CliOutput<OFProject[]>>;
+
+/**
+ * Query subtasks of a parent task in OmniFocus.
+ */
+export declare function querySubtasks(parentTaskId: string, options?: SubtaskQueryOptions): Promise<CliOutput<OFTaskWithChildren[]>>;
+
+/**
+ * Query tags from OmniFocus with optional filters.
+ */
+export declare function queryTags(options?: TagQueryOptions): Promise<CliOutput<OFTag[]>>;
+
+/**
+ * Query tasks from OmniFocus with optional filters.
+ */
+export declare function queryTasks(options?: TaskQueryOptions): Promise<CliOutput<OFTask[]>>;
+
+/**
+ * Repetition rule for recurring tasks.
+ */
+export declare interface RepetitionRule {
+    frequency: "daily" | "weekly" | "monthly" | "yearly";
+    interval: number;
+    repeatMethod: "due-again" | "defer-another";
+    daysOfWeek?: number[] | undefined;
+    dayOfMonth?: number | undefined;
+}
+
+/**
+ * Mark a project as reviewed in OmniFocus.
+ */
+export declare function reviewProject(projectId: string): Promise<CliOutput<ReviewResult>>;
+
+/**
+ * Result from a review operation.
+ */
+export declare interface ReviewResult {
+    projectId: string;
+    projectName: string;
+    lastReviewed: string;
+    nextReviewDate: string | null;
+}
+
+/**
+ * Execute an AppleScript and return the result.
+ * The script should return a value that can be parsed as JSON for structured data.
+ */
+export declare function runAppleScript<T>(script: string): Promise<AppleScriptResult<T>>;
+
+/**
+ * Execute an AppleScript file.
+ */
+export declare function runAppleScriptFile<T>(filePath: string, args?: string[]): Promise<AppleScriptResult<T>>;
+
+/**
+ * Options for searching tasks.
+ */
+export declare interface SearchOptions {
+    scope?: "name" | "note" | "both" | undefined;
+    limit?: number | undefined;
+    includeCompleted?: boolean | undefined;
+}
+
+/**
+ * Search tasks in OmniFocus.
+ */
+export declare function searchTasks(query: string, options?: SearchOptions): Promise<CliOutput<OFTask[]>>;
+
+/**
+ * Options for querying subtasks.
+ */
+export declare interface SubtaskQueryOptions {
+    completed?: boolean | undefined;
+    flagged?: boolean | undefined;
+}
+
+/**
+ * Create a successful CLI output.
+ */
+export declare function success<T>(data: T): CliOutput<T>;
+
+/**
+ * Options for querying tags.
+ */
+export declare interface TagQueryOptions {
+    parent?: string | undefined;
+}
+
+/**
+ * Options for querying tasks.
+ */
+export declare interface TaskQueryOptions {
+    project?: string | undefined;
+    tag?: string | undefined;
+    dueBefore?: string | undefined;
+    dueAfter?: string | undefined;
+    flagged?: boolean | undefined;
+    completed?: boolean | undefined;
+    available?: boolean | undefined;
+}
+
+/**
+ * Options for updating a task.
+ */
+export declare interface TaskUpdateOptions {
+    title?: string | undefined;
+    note?: string | undefined;
+    due?: string | undefined;
+    defer?: string | undefined;
+    flag?: boolean | undefined;
+    project?: string | undefined;
+    tags?: string[] | undefined;
+    estimatedMinutes?: number | undefined;
+    clearEstimate?: boolean | undefined;
+    repeat?: RepetitionRule | undefined;
+    clearRepeat?: boolean | undefined;
+}
+
+/**
+ * Update an existing tag in OmniFocus.
+ */
+export declare function updateTag(tagId: string, options: UpdateTagOptions): Promise<CliOutput<OFTag>>;
+
+/**
+ * Options for updating a tag.
+ */
+export declare interface UpdateTagOptions {
+    name?: string | undefined;
+    parentTagId?: string | undefined;
+    parentTagName?: string | undefined;
+}
+
+/**
+ * Update properties of an existing task in OmniFocus.
+ */
+export declare function updateTask(taskId: string, options: TaskUpdateOptions): Promise<CliOutput<OFTask>>;
+
+/**
+ * Update multiple tasks with the same properties in a single operation.
+ */
+export declare function updateTasks(taskIds: string[], options: TaskUpdateOptions): Promise<CliOutput<BatchResult<BatchCompleteItem>>>;
+
+/**
+ * Validate a date string for use with AppleScript.
+ * Returns null if valid (or empty), or a CliError if invalid.
+ *
+ * Note: We do basic validation here; the actual date parsing
+ * is done by AppleScript and more detailed errors come from there.
+ */
+export declare function validateDateString(dateStr: string): CliError | null;
+
+/**
+ * Validate an estimated minutes value.
+ * Returns null if valid (or undefined), or a CliError if invalid.
+ */
+export declare function validateEstimatedMinutes(minutes: number | undefined): CliError | null;
+
+/**
+ * Validate a folder name.
+ * Returns null if valid (or empty), or a CliError if invalid.
+ */
+export declare function validateFolderName(name: string | undefined): CliError | null;
+
+/**
+ * Validate an OmniFocus ID string.
+ * IDs are alphanumeric with possible dashes/underscores.
+ * Returns null if valid, or a CliError if invalid.
+ */
+export declare function validateId(id: string, type: "task" | "project" | "tag"): CliError | null;
+
+/**
+ * Validate a project name.
+ * Returns null if valid (or empty), or a CliError if invalid.
+ */
+export declare function validateProjectName(name: string | undefined): CliError | null;
+
+/**
+ * Validate a repetition rule.
+ * Returns null if valid (or undefined), or a CliError if invalid.
+ */
+export declare function validateRepetitionRule(rule: {
+    frequency: string;
+    interval: number;
+    repeatMethod: string;
+    daysOfWeek?: number[] | undefined;
+    dayOfMonth?: number | undefined;
+} | undefined): CliError | null;
+
+/**
+ * Validate a search query.
+ * Returns null if valid, or a CliError if invalid.
+ */
+export declare function validateSearchQuery(query: string): CliError | null;
+
+/**
+ * Validate a tag name for creation/update.
+ * Returns null if valid, or a CliError if invalid.
+ */
+export declare function validateTagName(name: string): CliError | null;
+
+/**
+ * Validate a list of tag names.
+ * Returns null if valid, or a CliError if any tag is invalid.
+ */
+export declare function validateTags(tags: string[] | undefined): CliError | null;
+
+export { }

package/dist/result.d.ts

@@ -0,0 +1,15 @@
+import type { CliOutput, CliError } from "./types.js";
+/**
+ * Create a successful CLI output.
+ */
+export declare function success<T>(data: T): CliOutput<T>;
+/**
+ * Create a failed CLI output with a structured error.
+ */
+export declare function failure<T = null>(error: CliError): CliOutput<T>;
+/**
+ * Create a failed CLI output with a simple string message.
+ * This is a convenience function that wraps the message in an UNKNOWN_ERROR.
+ */
+export declare function failureMessage<T = null>(message: string): CliOutput<T>;
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtD;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAMhD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,CAM/D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAEtE"}

package/dist/result.js

@@ -0,0 +1,29 @@
+import { ErrorCode, createError } from "./errors.js";
+/**
+ * Create a successful CLI output.
+ */
+export function success(data) {
+    return {
+        success: true,
+        data,
+        error: null,
+    };
+}
+/**
+ * Create a failed CLI output with a structured error.
+ */
+export function failure(error) {
+    return {
+        success: false,
+        data: null,
+        error,
+    };
+}
+/**
+ * Create a failed CLI output with a simple string message.
+ * This is a convenience function that wraps the message in an UNKNOWN_ERROR.
+ */
+export function failureMessage(message) {
+    return failure(createError(ErrorCode.UNKNOWN_ERROR, message));
+}
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAErD;;GAEG;AACH,MAAM,UAAU,OAAO,CAAI,IAAO;IAChC,OAAO;QACL,OAAO,EAAE,IAAI;QACb,IAAI;QACJ,KAAK,EAAE,IAAI;KACZ,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAW,KAAe;IAC/C,OAAO;QACL,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,IAAI;QACV,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAW,OAAe;IACtD,OAAO,OAAO,CAAI,WAAW,CAAC,SAAS,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC;AACnE,CAAC"}