{"_id":"@afjs/bark-sdk","_rev":"2-5c90fee7e46fa9f8557298b0ad2886bb","name":"@afjs/bark-sdk","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@afjs/bark-sdk","version":"1.0.0","keywords":["bark","push","notification","ios","nodejs","sdk"],"author":{"name":"TinsFox"},"license":"MIT","_id":"@afjs/bark-sdk@1.0.0","maintainers":[{"name":"tinsfox","email":"menhuluy@gmail.com"}],"dist":{"shasum":"c42f68206f2ca6bc6000755714a8dd80d04c9721","tarball":"https://registry.npmjs.org/@afjs/bark-sdk/-/bark-sdk-1.0.0.tgz","fileCount":5,"integrity":"sha512-D/q61T6ECohKs+uKtATuF2EfAWE0jUdfo/+8lpjuTBEsbA+AS2b+Cz6mnRxVWM1JQ65/HKwW0UFEGb4qgPsExw==","signatures":[{"sig":"MEUCIFM8tRY558DFeLZfQwBjIJg3koIJggzGN5KA60qObxc3AiEAxX6bVVrkrK94uu9Ch9Rl+VIMXnWk7gBxf4b2cW0Q0C0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28175},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js"}},"gitHead":"719fc41eab126895aa1f3c766f9786ef84b3a4fe","scripts":{"dev":"tsdown --watch","test":"echo \"Error: no test specified\" && exit 1","build":"tsdown","prepare":"pnpm build"},"_npmUser":{"name":"tinsfox","email":"menhuluy@gmail.com"},"_npmVersion":"10.9.2","description":"Bark推送服务的Node.js SDK","directories":{},"_nodeVersion":"22.14.0","dependencies":{"ofetch":"^1.4.1"},"_hasShrinkwrap":false,"devDependencies":{"tsdown":"^0.14.2","typescript":"^5.9.2","@types/node":"^20.19.12"},"_npmOperationalInternal":{"tmp":"tmp/bark-sdk_1.0.0_1762156008635_0.4337774662332754","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@afjs/bark-sdk","version":"1.0.1","description":"Bark推送服务的Node.js SDK","main":"dist/index.js","types":"dist/index.d.ts","type":"module","scripts":{"build":"tsdown","dev":"tsdown --watch","test":"echo \"Error: no test specified\" && exit 1","prepare":"pnpm build"},"keywords":["bark","push","notification","ios","nodejs","sdk"],"author":{"name":"TinsFox"},"license":"MIT","dependencies":{"ofetch":"^1.4.1"},"devDependencies":{"@types/node":"^20.19.12","tsdown":"^0.14.2","typescript":"^5.9.2"},"exports":{".":{"import":"./dist/index.js","require":"./dist/index.js","types":"./dist/index.d.ts"}},"_id":"@afjs/bark-sdk@1.0.1","gitHead":"719fc41eab126895aa1f3c766f9786ef84b3a4fe","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-uFwUM529hx6N0nADdEvRlX5gObdfXhMciD0xyouhwsBVlHQlYnMO4dHXlvfP05/WHqQLGHdMS1qIP7OB8RUMhw==","shasum":"1a9d8867092dc1427f4ffdb13cdbcd37cb7e2e13","tarball":"https://registry.npmjs.org/@afjs/bark-sdk/-/bark-sdk-1.0.1.tgz","fileCount":7,"unpackedSize":44232,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBCcJpuNBx0ls9pJUVfz8NhAyhxnO1cK6rBrZMJPgAhkAiEA+jv6ekRtijINMvuCHViSjq9vN3CP5Ej814vv8aZGlBo="}]},"_npmUser":{"name":"tinsfox","email":"menhuluy@gmail.com"},"directories":{},"maintainers":[{"name":"tinsfox","email":"menhuluy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/bark-sdk_1.0.1_1762156977608_0.3940153582844512"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-03T07:46:48.545Z","modified":"2025-11-03T08:02:58.051Z","1.0.0":"2025-11-03T07:46:48.907Z","1.0.1":"2025-11-03T08:02:57.836Z"},"author":{"name":"TinsFox"},"license":"MIT","keywords":["bark","push","notification","ios","nodejs","sdk"],"description":"Bark推送服务的Node.js SDK","maintainers":[{"name":"tinsfox","email":"menhuluy@gmail.com"}],"readme":"# Bark SDK\n\n[![npm version](https://img.shields.io/npm/v/@afjs/bark-sdk.svg)](https://www.npmjs.com/package/@afjs/bark-sdk)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n一个功能完整的 Bark 推送服务 Node.js SDK，支持 TypeScript，提供简洁易用的 API 接口。\n\n## 特性\n\n- 🚀 **简单易用** - 提供便捷函数和类实例两种使用方式\n- 📱 **功能完整** - 支持 Bark 的所有推送功能和参数\n- 🔧 **TypeScript** - 完整的类型定义，提供优秀的开发体验\n- 🎵 **声音支持** - 内置所有系统声音常量，支持自定义声音\n- 🔗 **链接推送** - 支持带链接的推送消息\n- 📊 **批量推送** - 支持批量发送多条消息\n- ⚙️ **灵活配置** - 支持自定义服务器地址和默认选项\n- 🏠 **自部署支持** - 完美支持自建 Bark 服务器，保护数据隐私\n- 🛡️ **错误处理** - 完善的错误处理和验证机制\n\n## 安装\n\n```bash\n# 使用 npm\nnpm install @afjs/bark-sdk\n\n# 使用 yarn\nyarn add @afjs/bark-sdk\n\n# 使用 pnpm\npnpm add @afjs/bark-sdk\n```\n\n## 快速开始\n\n### 基础使用\n\n```typescript\nimport { BarkClient, quickPush } from '@afjs/bark-sdk';\n\n// 方法 1: 使用便捷函数（推荐用于简单场景）\nawait quickPush('your-device-key', 'Hello Bark!', '测试标题');\n\n// 方法 2: 使用客户端实例（推荐用于复杂场景）\nconst client = new BarkClient({\n  deviceKey: 'your-device-key'\n});\n\nawait client.sendText('Hello Bark!', '测试标题');\n```\n\n### 使用自建服务器\n\n如果您部署了自己的 Bark 服务器，可以通过 `serverUrl` 参数指定：\n\n```typescript\n// 使用便捷函数指定自建服务器\nawait quickPush(\n  'your-device-key',\n  'Hello Bark!',\n  '测试标题',\n  'https://your-bark-server.com'  // 自建服务器地址\n);\n\n// 使用客户端实例指定自建服务器\nconst client = new BarkClient({\n  deviceKey: 'your-device-key',\n  serverUrl: 'https://your-bark-server.com'  // 自建服务器地址\n});\n\nawait client.sendText('Hello from self-hosted server!', '自建服务器');\n```\n\n> 💡 **提示**: 使用自建 Bark 服务器可以更好地保护您的数据隐私，避免推送内容经过第三方服务器。\n\n### 获取设备密钥\n\n1. 在 App Store 下载 [Bark](https://apps.apple.com/app/bark-customed-notifications/id1403753865) 应用\n2. 打开应用，复制显示的设备密钥（通常是 22 位字符串）\n3. 将密钥用于 SDK 配置\n\n## API 文档\n\n### BarkClient 类\n\n#### 构造函数\n\n```typescript\nconst client = new BarkClient(config: BarkConfig);\n```\n\n**BarkConfig 接口：**\n\n```typescript\ninterface BarkConfig {\n  /** 设备密钥（必需） */\n  deviceKey: string;\n  /**\n   * Bark 服务器地址（可选，默认为官方服务器）\n   * 如果您部署了自己的 Bark 服务器，请在此指定完整的服务器地址\n   * 例如: 'https://your-bark-server.com'\n   */\n  serverUrl?: string;\n  /** 默认推送选项（可选） */\n  defaultOptions?: Partial<BarkOptions>;\n}\n```\n\n#### 主要方法\n\n##### push(options: BarkOptions)\n\n发送自定义推送消息，支持所有 Bark 参数。\n\n```typescript\nawait client.push({\n  title: '系统通知',\n  body: '这是推送内容',\n  level: 'timeSensitive',\n  sound: 'bell',\n  url: 'https://example.com',\n  badge: 5\n});\n```\n\n##### sendText(text: string, title?: string)\n\n发送简单文本消息。\n\n```typescript\nawait client.sendText('消息内容', '可选标题');\n```\n\n##### sendLink(text: string, url: string, title?: string)\n\n发送带链接的消息。\n\n```typescript\nawait client.sendLink('点击查看详情', 'https://example.com', '链接通知');\n```\n\n##### sendWithSound(text: string, sound: string, title?: string)\n\n发送带自定义声音的消息。\n\n```typescript\nimport { BarkSounds } from '@afjs/bark-sdk';\n\nawait client.sendWithSound('重要通知', BarkSounds.ALARM, '警报');\n```\n\n##### sendUrgent(text: string, title?: string)\n\n发送重要消息（时间敏感级别）。\n\n```typescript\nawait client.sendUrgent('紧急情况！', '紧急通知');\n```\n\n##### sendSilent(text: string, title?: string)\n\n发送静默消息（被动级别）。\n\n```typescript\nawait client.sendSilent('后台任务完成', '系统通知');\n```\n\n##### test()\n\n发送测试消息，用于验证配置是否正确。\n\n```typescript\nawait client.test();\n```\n\n### BarkOptions 接口\n\n完整的推送选项配置：\n\n```typescript\ninterface BarkOptions {\n  /** 推送标题 */\n  title?: string;\n  /** 推送内容（必需） */\n  body: string;\n  /** 推送分组，默认为应用名称 */\n  group?: string;\n  /** 推送图标，可以是 URL */\n  icon?: string;\n  /** 推送声音，可以指定系统声音名称 */\n  sound?: string;\n  /** 推送链接，点击推送时打开的 URL */\n  url?: string;\n  /** 是否自动复制推送内容，默认为 0 */\n  automaticallyCopy?: 0 | 1;\n  /** 是否复制推送内容，默认为 0 */\n  copy?: 0 | 1;\n  /** 推送中断等级 */\n  level?: \"active\" | \"timeSensitive\" | \"passive\";\n  /** 推送角标数量 */\n  badge?: number;\n  /** 是否归档推送，默认为 1 */\n  isArchive?: 0 | 1;\n}\n```\n\n### 便捷函数\n\n#### quickPush\n\n快速发送推送消息的便捷函数。\n\n```typescript\nimport { quickPush } from '@afjs/bark-sdk';\n\nawait quickPush(\n  'your-device-key',\n  '消息内容',\n  '可选标题',\n  'https://custom-server.com' // 可选的自定义服务器\n);\n```\n\n#### createBarkClient\n\n创建 BarkClient 实例的便捷函数。\n\n```typescript\nimport { createBarkClient } from '@afjs/bark-sdk';\n\nconst client = createBarkClient('your-device-key', 'https://custom-server.com');\n```\n\n#### validateDeviceKey\n\n验证设备密钥格式是否正确。\n\n```typescript\nimport { validateDeviceKey } from '@afjs/bark-sdk';\n\nif (validateDeviceKey('your-device-key')) {\n  console.log('设备密钥格式正确');\n}\n```\n\n### 内置声音常量\n\nSDK 提供了所有 iOS 系统声音的常量：\n\n```typescript\nimport { BarkSounds } from '@afjs/bark-sdk';\n\n// 使用预定义声音\nawait client.sendWithSound('测试消息', BarkSounds.BELL);\nawait client.sendWithSound('警报消息', BarkSounds.ALARM);\nawait client.sendWithSound('邮件通知', BarkSounds.NEWMAIL);\n\n// 可用的声音常量\nBarkSounds.DEFAULT      // 默认\nBarkSounds.BELL         // 铃声\nBarkSounds.BIRDSONG     // 鸟鸣\nBarkSounds.BLOOM        // 绽放\nBarkSounds.CALYPSO      // 卡利普索\nBarkSounds.CHIME        // 钟声\nBarkSounds.CHOO         // 火车\nBarkSounds.DESCENT      // 下降\nBarkSounds.ELECTRONIC   // 电子音\nBarkSounds.FANFARE      // 号角\nBarkSounds.GLASS        // 玻璃\nBarkSounds.GOTOSLEEP    // 睡眠\nBarkSounds.HEALTHNOTIFICATION // 健康通知\nBarkSounds.HORN         // 喇叭\nBarkSounds.LADDER       // 梯子\nBarkSounds.MAILSENT     // 邮件发送\nBarkSounds.MINUET       // 小步舞曲\nBarkSounds.MULTIWAYINVITATION // 多方邀请\nBarkSounds.NEWMAIL      // 新邮件\nBarkSounds.NEWSFLASH    // 新闻快报\nBarkSounds.NOIR         // 黑色\nBarkSounds.PAYMENTSUCCESS // 支付成功\nBarkSounds.SHAKE        // 摇动\nBarkSounds.SHERWOODFOREST // 舍伍德森林\nBarkSounds.SILENCE      // 静音\nBarkSounds.SPELL        // 咒语\nBarkSounds.SUSPENSE     // 悬疑\nBarkSounds.TELEGRAPH    // 电报\nBarkSounds.TIPTOES      // 踮脚\nBarkSounds.TYPEWRITERS  // 打字机\nBarkSounds.UPDATE       // 更新\n```\n\n## 使用示例\n\n### 基础示例\n\n```typescript\nimport { BarkClient, quickPush, BarkSounds } from '@afjs/bark-sdk';\n\nconst DEVICE_KEY = 'your-device-key-here';\n\nasync function basicExample() {\n  // 方法 1: 使用便捷函数\n  await quickPush(DEVICE_KEY, '这是一条测试消息', 'Bark SDK');\n\n  // 方法 2: 使用客户端实例\n  const client = new BarkClient({\n    deviceKey: DEVICE_KEY,\n    defaultOptions: {\n      group: 'Bark SDK Examples',\n      sound: BarkSounds.BELL,\n    },\n  });\n\n  // 简单文本消息\n  await client.sendText('Hello from Bark SDK!', '问候');\n\n  // 带链接的消息\n  await client.sendLink(\n    '点击查看 Bark SDK 文档',\n    'https://github.com/tinsfox/fox-server',\n    '文档链接'\n  );\n\n  // 重要消息\n  await client.sendUrgent('这是一条重要消息', '紧急通知');\n\n  // 静默消息\n  await client.sendSilent('这是一条静默消息', '静默通知');\n}\n```\n\n### 高级示例\n\n```typescript\nimport { BarkClient, BarkSounds, validateDeviceKey } from '@afjs/bark-sdk';\n\nconst DEVICE_KEY = 'your-device-key-here';\n\nasync function advancedExample() {\n  // 验证设备密钥格式\n  if (!validateDeviceKey(DEVICE_KEY)) {\n    throw new Error('设备密钥格式不正确');\n  }\n\n  const client = new BarkClient({\n    deviceKey: DEVICE_KEY,\n    defaultOptions: {\n      group: 'Advanced Examples',\n      isArchive: 1,\n    },\n  });\n\n  // 高级推送选项\n  await client.push({\n    title: '系统监控警报',\n    body: 'CPU 使用率超过 90%，请及时处理',\n    level: 'timeSensitive',\n    sound: BarkSounds.ALARM,\n    badge: 5,\n    url: 'https://monitor.example.com',\n    automaticallyCopy: 1,\n    icon: 'https://example.com/warning-icon.png',\n  });\n\n  // 批量推送\n  const notifications = [\n    {\n      title: '任务完成',\n      body: '数据备份已完成',\n      sound: BarkSounds.CHIME,\n    },\n    {\n      title: '新用户注册',\n      body: 'user@example.com 已注册',\n      sound: BarkSounds.NEWMAIL,\n    },\n    {\n      title: '服务器状态',\n      body: '所有服务运行正常',\n      level: 'passive' as const,\n    },\n  ];\n\n  const results = await Promise.allSettled(\n    notifications.map(notification => client.push(notification))\n  );\n\n  results.forEach((result, index) => {\n    if (result.status === 'fulfilled') {\n      console.log(`通知 ${index + 1} 发送成功`);\n    } else {\n      console.error(`通知 ${index + 1} 发送失败:`, result.reason.message);\n    }\n  });\n}\n```\n\n### 定时推送示例\n\n```typescript\nimport { BarkClient } from '@afjs/bark-sdk';\n\nconst client = new BarkClient({\n  deviceKey: 'your-device-key'\n});\n\n// 定时推送函数\nfunction scheduleNotification(delay: number, message: string) {\n  setTimeout(async () => {\n    try {\n      await client.sendText(message, '定时通知');\n      console.log(`定时消息发送成功: ${message}`);\n    } catch (error) {\n      console.error('定时消息发送失败:', error.message);\n    }\n  }, delay);\n}\n\n// 设置多个定时推送\nscheduleNotification(2000, '2秒后的消息');\nscheduleNotification(4000, '4秒后的消息');\nscheduleNotification(6000, '6秒后的消息');\n```\n\n### 错误处理示例\n\n```typescript\nimport { BarkClient } from '@afjs/bark-sdk';\n\nconst client = new BarkClient({\n  deviceKey: 'your-device-key'\n});\n\nasync function handleErrors() {\n  try {\n    await client.sendText('测试消息', '测试');\n    console.log('消息发送成功');\n  } catch (error) {\n    if (error.message.includes('设备密钥')) {\n      console.error('设备密钥错误，请检查配置');\n    } else if (error.message.includes('网络')) {\n      console.error('网络连接失败，请检查网络');\n    } else {\n      console.error('发送失败:', error.message);\n    }\n  }\n}\n```\n\n## 配置选项\n\n### 自定义服务器\n\n如果您使用自建的 Bark 服务器，可以指定自定义服务器地址：\n\n```typescript\nconst client = new BarkClient({\n  deviceKey: 'your-device-key',\n  serverUrl: 'https://your-bark-server.com'\n});\n```\n\n### 默认选项\n\n可以为客户端设置默认的推送选项，这些选项会应用到所有推送消息：\n\n```typescript\nconst client = new BarkClient({\n  deviceKey: 'your-device-key',\n  defaultOptions: {\n    group: 'MyApp',\n    sound: BarkSounds.CHIME,\n    isArchive: 1,\n    level: 'active'\n  }\n});\n\n// 这条消息会自动应用上述默认选项\nawait client.sendText('使用默认配置的消息');\n```\n\n### 推送级别说明\n\n- `active`：默认级别，正常显示推送\n- `timeSensitive`：时间敏感，即使在勿扰模式下也会显示\n- `passive`：被动级别，不会点亮屏幕或播放声音\n\n### 声音配置\n\n```typescript\n// 使用预定义声音常量\nawait client.sendWithSound('消息', BarkSounds.BELL);\n\n// 使用自定义声音名称\nawait client.sendWithSound('消息', 'custom-sound');\n\n// 静音推送\nawait client.sendWithSound('消息', BarkSounds.SILENCE);\n```\n\n## 最佳实践\n\n### 1. 错误处理\n\n始终使用 try-catch 包装推送操作：\n\n```typescript\ntry {\n  await client.sendText('重要消息');\n} catch (error) {\n  // 记录错误日志\n  console.error('推送失败:', error.message);\n  // 可以考虑重试或使用备用通知方式\n}\n```\n\n### 2. 批量推送\n\n对于多条消息，使用 `Promise.allSettled` 确保部分失败不影响其他消息：\n\n```typescript\nconst messages = ['消息1', '消息2', '消息3'];\nconst results = await Promise.allSettled(\n  messages.map(msg => client.sendText(msg))\n);\n```\n\n### 3. 频率控制\n\n避免短时间内发送大量推送，建议添加延迟：\n\n```typescript\nfor (const message of messages) {\n  await client.sendText(message);\n  await new Promise(resolve => setTimeout(resolve, 1000)); // 1秒延迟\n}\n```\n\n### 4. 设备密钥验证\n\n在使用前验证设备密钥格式：\n\n```typescript\nimport { validateDeviceKey } from '@afjs/bark-sdk';\n\nif (!validateDeviceKey(deviceKey)) {\n  throw new Error('设备密钥格式不正确');\n}\n```\n\n### 5. 环境配置\n\n在生产环境中，将设备密钥等敏感信息存储在环境变量中：\n\n```typescript\nconst client = new BarkClient({\n  deviceKey: process.env.BARK_DEVICE_KEY!,\n  serverUrl: process.env.BARK_SERVER_URL\n});\n```\n\n## 故障排除\n\n### 常见问题\n\n1. **推送发送失败**\n   - 检查设备密钥是否正确\n   - 确认网络连接正常\n   - 验证服务器地址是否可访问\n\n2. **收不到推送**\n   - 确认 Bark 应用已安装并正确配置\n   - 检查 iOS 通知权限设置\n   - 验证设备密钥是否匹配\n\n3. **声音不播放**\n   - 检查设备静音模式设置\n   - 确认声音名称拼写正确\n   - 验证推送级别设置\n\n### 调试技巧\n\n启用详细日志输出：\n\n```typescript\nconst client = new BarkClient({\n  deviceKey: 'your-device-key'\n});\n\n// 测试连接\ntry {\n  const result = await client.test();\n  console.log('测试成功:', result);\n} catch (error) {\n  console.error('测试失败:', error.message);\n}\n```\n\n## 更新日志\n\n### v1.0.0\n- 初始版本发布\n- 支持所有 Bark 推送功能\n- 提供 TypeScript 类型定义\n- 包含完整的示例和文档\n\n## 许可证\n\nMIT License - 详见 [LICENSE](LICENSE) 文件。\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request！\n\n## 相关链接\n\n- [Bark 官方应用](https://apps.apple.com/app/bark-customed-notifications/id1403753865)\n- [Bark 服务端项目](https://github.com/Finb/Bark)\n\n---\n\n如果这个 SDK 对您有帮助，请给项目一个 ⭐️ Star！\n","readmeFilename":"README.md"}