{"id":13588610,"url":"https://github.com/caroso1222/node-reminders","last_synced_at":"2025-04-12T15:30:56.290Z","repository":{"id":38227613,"uuid":"256498708","full_name":"caroso1222/node-reminders","owner":"caroso1222","description":"🐝A NodeJS and TypeScript wrapper for macOS Reminders","archived":false,"fork":false,"pushed_at":"2023-01-06T03:38:15.000Z","size":1923,"stargazers_count":43,"open_issues_count":17,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-26T10:03:40.990Z","etag":null,"topics":["automation","jxa","macos","nodejs-wrapper","osx","reminders","typescript-wrapper"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caroso1222.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-17T12:36:52.000Z","updated_at":"2024-10-08T12:23:13.000Z","dependencies_parsed_at":"2023-02-05T05:46:15.883Z","dependency_job_id":null,"html_url":"https://github.com/caroso1222/node-reminders","commit_stats":{"total_commits":15,"total_committers":3,"mean_commits":5.0,"dds":0.2666666666666667,"last_synced_commit":"533044ab47405b007f6c4a37f92ad9b3f54019a3"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caroso1222%2Fnode-reminders","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caroso1222%2Fnode-reminders/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caroso1222%2Fnode-reminders/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caroso1222%2Fnode-reminders/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caroso1222","download_url":"https://codeload.github.com/caroso1222/node-reminders/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248589343,"owners_count":21129590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","jxa","macos","nodejs-wrapper","osx","reminders","typescript-wrapper"],"created_at":"2024-08-01T15:06:49.165Z","updated_at":"2025-04-12T15:30:55.620Z","avatar_url":"https://github.com/caroso1222.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# node-reminders\n[![npm version](https://badge.fury.io/js/node-reminders.svg)](https://badge.fury.io/js/node-reminders)\n[![Build Status](https://travis-ci.com/caroso1222/node-reminders.svg?branch=master)](https://travis-ci.com/caroso1222/node-reminders)\n[![codecov](https://codecov.io/gh/caroso1222/node-reminders/branch/master/graph/badge.svg)](https://codecov.io/gh/caroso1222/node-reminders)\n\n\nA NodeJS and TypeScript wrapper for the macOS Reminders App.\n\n- 🔥 Easy to use interface to create, retrieve, update and delete lists and reminders\n- 👾 CommonJS and ES6 modules\n- 🤖 Typings available\n- 🎩 JXA-based communication with the Reminders App\n\n# Installation\n\n```\nnpm i node-reminders\n```\n\n# Usage\n\nUse it in JavaScript with CommonJS or in TypeScript with ES6 modules.\n\n```typescript\n// with JavaScript\nconst reminders = require('node-reminders');\n\n// with TypeScript\nimport * as reminders from 'node-reminders';\n\nasync function run() {\n  // get lists\n  const lists = await reminders.getLists();\n\n  // create reminder\n  const laterToday = new Date();\n  laterToday.setHours(laterToday.getHours() + 8);\n\n  reminders.createReminder(lists[0].id, {\n    name: 'Call John',\n    body: 'Catch up on the plan',\n    remindMeDate: laterToday,\n  });\n}\n```\n\n# API\n\n#### `getLists(): Promise\u003cList[]\u003e`\n\nResolves with the list of reminders [lists](#list).\n\n#### `getList(id: string): Promise\u003cList\u003e`\n\nResolves with the detail of a specific [list](#list).\n\n#### `createList(data: List): Promise\u003cstring\u003e`\n\nCreates a new reminders list and resolves with its ID.\n\n#### `getReminders(listId: string, props?: Array\u003ckeyof Reminder\u003e): Promise\u003cReminder[]\u003e`\n\nResolves with the [reminders](#reminder) of a given list. Optionally specify which props to retrieve. The more props, the slower the query. See the reminders example for more.\n\n#### `getReminder(reminderId: string, props?: Array\u003ckeyof Reminder\u003e): Promise\u003cReminder\u003e`\n\nResolves with the information of a specific reminder. Optionally specify which props to retrieve.\n\n#### `updateReminder(id: string, data: Partial\u003cReminder\u003e): Promise\u003cstring\u003e`\n\nUpdates a reminder and resolves with its ID. Pass only the subset of parameters to modify.\n\n#### `deleteReminder(id: string): Promise\u003ctrue\u003e`\n\nDeletes a reminder and resolves with `true` if successful. Throws exception otherwise.\n\n#### `createReminder(listId: string, data: Partial\u003cReminder\u003e): Promise\u003cstring\u003e`\n\nCreates a reminder in a list and resolves with its ID. See [example](#create-reminder).\n\n# Examples\n\n## List\n\n#### Get Lists\n\n```typescript\nimport { getLists } from 'node-reminders';\n\n(async () =\u003e {\n  const lists = await getLists();\n  console.log(lists);\n\n  /**\n   * [\n   *  { name: 'Reminders', id: '2480C298-017A-11EB-BBBF-CB4F4FDF3602' },\n   *  { name: 'Family TODO', id: '3D8660F9-9925-461A-B5FB-B0DDD56B7925' }\n   * ]\n   */\n})();\n```\n\n#### Get List\n\n```typescript\nimport { getList } from 'node-reminders';\n\n(async () =\u003e {\n  const list = await getList('2480C298-017A-11EB-BBBF-CB4F4FDF3602');\n  console.log(list);\n\n  /**\n   * { name: 'Reminders', id: '2480C298-017A-11EB-BBBF-CB4F4FDF3602' }\n   */\n})();\n```\n\n#### Create List\n\n```typescript\nimport { createList } from 'node-reminders';\n\n(async () =\u003e {\n  const newList = await createList({ name: 'June Reminders' });\n  console.log(newList);\n\n  /**\n   * '8AE21B5E-466A-4FDA-B59B-10B8CC80418A'\n   */\n})();\n```\n\n\n*Note: List deletion is not supported. It's simply not allowed either via `.jxa` or `.applescript` directly.*\n\n## Reminders\n\n#### Get reminders\n\n```typescript\nimport { getReminders } from 'node-reminders';\n\n(async () =\u003e {\n  const reminderList = await getReminders(\n    '2480C298-017A-11EB-BBBF-CB4F4FDF3602',\n    [ 'name', 'id', 'remindMeDate', 'completed', 'priority' ] // fetch only a subset of properties\n  );\n  console.log(reminderList);\n\n  /**\n      [\n        { name: 'Call John',\n          id: 'x-apple-reminder://776E5676-BB79-4095-8317-C94863814B50',\n          remindMeDate: '2020-04-13T15:02:34.000Z',\n          completed: true,\n          priority: 0 },\n        { name: 'Pay the bills',\n          id: 'x-apple-reminder://8D9A728B-24C3-420B-A664-352B3C06E689',\n          remindMeDate: '2025-04-15T15:09:08.000Z',\n          completed: false,\n          priority: 0 },\n        { name: 'Ping Lina',\n          id: 'x-apple-reminder://6C6D0961-B80D-4967-A9D6-B73F8278A117',\n          remindMeDate: null,\n          completed: false,\n          priority: 0 },\n      ]\n   */\n})();\n```\n\n#### Get reminder\n\n```typescript\nimport { getReminder } from 'node-reminders';\n\n(async () =\u003e {\n  const reminder = await getReminder(\n    'x-apple-reminder://8D9A728B-24C3-420B-A664-352B3C06E689',\n    ['name', 'remindMeDate', 'completed']\n  );\n  console.log(reminder);\n\n  /**\n    {\n      name: 'Pay the bills',\n      remindMeDate: '2025-04-15T15:09:08.000Z',\n      completed: false\n    }\n   */\n})();\n```\n\n#### Update reminder\n\n```typescript\nimport { updateReminder } from 'node-reminders';\n\n(async () =\u003e {\n  const oneMonthLater = new Date();\n  oneMonthLater.setFullYear(oneMonthLater.getMonth() + 1);\n\n  const edited = await reminders.updateReminder(\n    'x-apple-reminder://8D9A728B-24C3-420B-A664-352B3C06E689',\n    {\n      name: 'Pay cable',\n      completed: true,\n      remindMeDate: oneMonthLater,\n    }\n  );\n  console.log(edited);\n\n  /**\n   * 'x-apple-reminder://8D9A728B-24C3-420B-A664-352B3C06E689'\n   */\n})();\n```\n\n#### Delete reminder\n\n```typescript\nimport { deleteReminder } from 'node-reminders';\n\n(async () =\u003e {\n  try {\n    const deletedReminder = await reminders.deleteReminder('2480C298-017A-11EB-BBBF-CB4F4FDF3602');\n    console.log(deleteReminder);\n  } catch(e) {\n    console.error('Something failed. Could not delete the reminder.');\n  }\n\n  /**\n   * true\n   */\n})();\n```\n\n#### Create reminder\n\n```typescript\nimport { createReminder } from 'node-reminders';\n\n(async () =\u003e {\n  const laterToday = new Date();\n  laterToday.setHours(laterToday.getHours() + 8);\n\n  const newReminder = await createReminder(\n    '2480C298-017A-11EB-BBBF-CB4F4FDF3602',\n    {\n      name: 'Update daily journal',\n      body: 'Lots of things going on',\n      remindMeDate: laterToday,\n      completed: false,\n  });\n  console.log(newReminder);\n\n  /**\n   * 'x-apple-reminder://32E91818-16FB-4E89-9C36-4960207AEA12\n   */\n})();\n```\n\n# Interfaces\n\nThe interface prop names are self-explanatory. Descriptions are intentionally omitted.\n\n### `List`\n\nParam | Type \n------|------\nname|string\nid|string\n\n### `Reminder`\n\nParam | Type \n------|------\nname|string\nbody|string\nid|string\ncomplete|boolean\ncompletionDate|Date\ncreationDate|Date\ndueDate|Date\nmodificationDate|Date\nremindMeDate|Date\npriority|number\n\n# How it works\n\nUnder the hood, this library is an interface to run [JXA](https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/index.html) scripts in the terminal. JXA is JavaScript for OSX automation. You can find all the scripts in [`src/jxa`](src/jxa). Arguments and outputs are passed back and forth via *stringified* objects.\n\n# Licence\n\nMIT © [Carlos Roso](https://carlosroso.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaroso1222%2Fnode-reminders","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaroso1222%2Fnode-reminders","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaroso1222%2Fnode-reminders/lists"}