Protocol Launcher

English

简体中文

English

简体中文

Appearance

BusyCal ​

BusyCal is a calendar app for macOS and iOS. Protocol Launcher allows you to generate BusyCal deep links to create events and tasks, open dates, and switch views.

Usage ​

There are two ways to use this library:

  • On-Demand import from subpaths enables tree-shaking and keeps bundles small.
  • Full Import from the root package is convenient but includes all app modules.

Pick On-Demand for production builds; Full Import is fine for quick scripts or demos.

Select Installation Method

On-Demand
Recommended. Optimized for production.
Full Import
Convenient. Good for quick scripts.

macOS: New Event and Task ​

Use BusyCal's busycalevent://new/ URL with a natural-language string. Include calendar names such as /Work and URLs in angle brackets inside the description string, exactly as BusyCal documents; the helper only percent-encodes the path segment.

On-Demand
ts
import { newEvent, newTask } from 'protocol-launcher/busycal'

const eventUrl = newEvent({
  description: 'Staff meeting Thursday at 10am',
})

const taskUrl = newTask({
  description: 'Pay Taxes April 15!!! /Personal',
})
Create BusyCal Event

macOS: Find, Date, and Filter ​

find() maps to busycalevent://find/<Calendar>/<Title>/<DateTime> or busycalevent://find/<Calendar>/<Title>/<Date>. Leave calendar undefined to search all calendars. openFilter() uses BusyCal's shared Calendar Set or Smart Filter handler.

On-Demand
ts
import { find, openDate, openFilter } from 'protocol-launcher/busycal'

const findUrl = find({
  title: 'Buy Toner',
})

const dateUrl = openDate({
  date: '2021-05-31',
})

const filterUrl = openFilter({
  name: 'home',
})
Find ItemOpen DateOpen Filter

macOS: Quick Entry and Subscription ​

BusyCal documents Quick Entry URLs for a new event or task, and webcal:// URLs for calendar subscriptions.

On-Demand
ts
import { openEventQuickEntry, openTaskQuickEntry, subscribeCalendar } from 'protocol-launcher/busycal'

const eventQuickEntryUrl = openEventQuickEntry()
const taskQuickEntryUrl = openTaskQuickEntry()
const subscriptionUrl = subscribeCalendar({
  url: 'webcal://example.com/calendar.ics',
})
Event Quick EntryTask Quick EntrySubscribe Calendar

macOS: Sync, DND, and Settings ​

BusyCal also documents URL handlers for forcing sync, setting Do Not Disturb minutes, logging level, and crash reporting. These URLs can change BusyCal state, so the docs show generated strings without launch buttons.

On-Demand
ts
import { syncCalDAV, syncWebDAV, setDoNotDisturb, setLogLevel, setCrashReporting } from 'protocol-launcher/busycal'

const caldavUrl = syncCalDAV()
const webdavUrl = syncWebDAV()
const dndUrl = setDoNotDisturb({ minutes: 15 })
const loggingUrl = setLogLevel({ level: 3 })
const crashReportingUrl = setCrashReporting({ option: 1 })

iOS ​

BusyCal for iOS uses busycal://new/, busycal://date/, and busycal://launch/. For newIosEvent() and newIosTask(), pass autosave: true or autosave: 1 only when you want the documented auto-save behavior.

On-Demand
ts
import { newIosEvent, newIosTask, openIosDate, launchIosView } from 'protocol-launcher/busycal'

const eventUrl = newIosEvent({
  description: 'Baseball game tomorrow',
})

const taskUrl = newIosTask({
  description: 'Call Bob tomorrow',
})

const dateUrl = openIosDate({
  date: '2021-05-31',
})

const launchUrl = launchIosView({
  view: 'day',
})
New iOS EventOpen iOS DateOpen iOS View

Generated URLs ​

ts
newEvent({ description: 'Staff meeting Thursday at 10am' })
// => 'busycalevent://new/Staff%20meeting%20Thursday%20at%2010am'

newTask({ description: 'Pay Taxes April 15!!! /Personal' })
// => 'busycalevent://new/-Pay%20Taxes%20April%2015!!!%20%2FPersonal'

find({ title: 'Buy Toner' })
// => 'busycalevent://find//Buy%20Toner'

openDate({ date: '2021-05-31' })
// => 'busycalevent://date/2021-05-31'

openFilter({ name: 'home' })
// => 'busycal://filter/home'

openEventQuickEntry()
// => 'busycal://newEvent'

openTaskQuickEntry()
// => 'busycal://newTask'

subscribeCalendar({ url: 'webcal://example.com/calendar.ics' })
// => 'webcal://example.com/calendar.ics'

syncCalDAV()
// => 'busycalsync://caldav'

syncWebDAV()
// => 'busycalsync://webdav'

setDoNotDisturb({ minutes: 15 })
// => 'busycaldnd://15'

setLogLevel({ level: 3 })
// => 'busycalsetting://loglevel/3'

setCrashReporting({ option: 1 })
// => 'busycalsetting://crashreporting/1'

newIosEvent({ description: 'Project review 3pm /Work', autosave: 1 })
// => 'busycal://new/Project%20review%203pm%20%2FWork//1'

newIosTask({ description: 'Call Bob tomorrow' })
// => 'busycal://new/-Call%20Bob%20tomorrow'

newIosTask({ description: 'Buy Toner /Shopping <www.amazon.com>', autosave: true })
// => 'busycal://new/-Buy%20Toner%20%2FShopping%20%3Cwww.amazon.com%3E/true'

openIosDate({ date: 'now' })
// => 'busycal://date/now'

launchIosView({ view: 'tasks' })
// => 'busycal://launch/tasks'

References ​