{"_id":"@6digit/satellite-convex","_rev":"5-462bbd313d9623487ab28ae60badbf87","name":"@6digit/satellite-convex","dist-tags":{"latest":"0.3.2"},"versions":{"0.1.0":{"name":"@6digit/satellite-convex","version":"0.1.0","keywords":["convex","satellite","tools","proxy","local-development","ai","coding-assistant","6digit"],"author":{"name":"6digit"},"license":"MIT","_id":"@6digit/satellite-convex@0.1.0","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"homepage":"https://6digit.studio","bugs":{"url":"https://github.com/6digit/satellite-convex/issues"},"dist":{"shasum":"6fadddc537c69f5429247eba0999c77cea04c435","tarball":"https://registry.npmjs.org/@6digit/satellite-convex/-/satellite-convex-0.1.0.tgz","fileCount":15,"integrity":"sha512-jqSWcBUVl0nvZM30TUN9gtmfok7UtiIrHaB/bzn/nDdeyGTpT6iD46if/MZNpxk1YnleEqEggN2omGGEDh14hg==","signatures":[{"sig":"MEUCIQDekSCclSZ+Fc/Fh+XRoK4pGYO9gWzGDn9658o19B5d/QIgNhobevku/S4qnnpzyt8/C4bv0o3HxABr96sU916Fu0M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29359},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"30ce3b3655a845cd3383abaf209a1a475ccaf061","scripts":{"dev":"tsx src/index.ts","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"repository":{"url":"git+https://github.com/6digit/satellite-convex.git","type":"git"},"_npmVersion":"11.4.2","description":"Server-side Convex integration for 6digit-satellite with transparent tool proxying and session management","directories":{},"_nodeVersion":"23.2.0","dependencies":{"zod":"^3.22.0","convex":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/satellite-convex_0.1.0_1753559417426_0.036804759298622924","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@6digit/satellite-convex","version":"0.2.0","keywords":["convex","satellite","tools","proxy","local-development","ai","coding-assistant","6digit"],"author":{"name":"6digit"},"license":"MIT","_id":"@6digit/satellite-convex@0.2.0","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"homepage":"https://6digit.studio","bugs":{"url":"https://github.com/6digit/satellite-convex/issues"},"dist":{"shasum":"c31fd0eabd1ff9fdfa97726f691113d94ceed25a","tarball":"https://registry.npmjs.org/@6digit/satellite-convex/-/satellite-convex-0.2.0.tgz","fileCount":15,"integrity":"sha512-r7wFThjXRNy2HE9T2xABaPKtw+Ef5DrByHtkscVlsRGtCUujnsqqSaJWT1p7rpdsBq4xE5ij6qPvEqzruZhLbg==","signatures":[{"sig":"MEUCIBuMziDye1ItaMipwEuZdw7j3/ip3bmeSEi0Wj9r/mmmAiEAp9KcZTvAEvf9wESUSm832B7a8r0V2+Vrdhes1gKsgcQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29359},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"7eded2d6e65d0948521b23ae9c91901f3bd6034d","scripts":{"dev":"tsx src/index.ts","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"repository":{"url":"git+https://github.com/6digit/satellite-convex.git","type":"git"},"_npmVersion":"11.4.2","description":"Server-side Convex integration for 6digit-satellite with transparent tool proxying and session management","directories":{},"_nodeVersion":"23.2.0","dependencies":{"zod":"^3.22.0","convex":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/satellite-convex_0.2.0_1753653098829_0.296126288358016","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@6digit/satellite-convex","version":"0.3.0","keywords":["convex","satellite","tools","proxy","local-development","ai","coding-assistant","6digit"],"author":{"name":"6digit"},"license":"MIT","_id":"@6digit/satellite-convex@0.3.0","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"homepage":"https://6digit.studio","bugs":{"url":"https://github.com/6digit/satellite-convex/issues"},"dist":{"shasum":"d824f7f3f6866b05325539540e6c4cf11b1e5c4d","tarball":"https://registry.npmjs.org/@6digit/satellite-convex/-/satellite-convex-0.3.0.tgz","fileCount":15,"integrity":"sha512-Y6F6iGbm/jUJurTyMY+4VV4Zo/3Xtbv1xoW4bGxMEXwce9mn/4IztMyOjhnj0von/fV2xH+/3TRfzeaQ672M8A==","signatures":[{"sig":"MEUCIQCrda+nqksGPdilTxKw9GMUYmnKK0fflOxpoH2JTqQS8wIgdop93X6usHos15eWcVfKtT9oJmhmeMvbLe7tHG5iWdA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29761},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"8453c0741df9e4fdde95398f70de57c0fd9fd252","scripts":{"dev":"tsx src/index.ts","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"repository":{"url":"git+https://github.com/6digit/satellite-convex.git","type":"git"},"_npmVersion":"11.4.2","description":"Server-side Convex integration for 6digit-satellite with transparent tool proxying and session management","directories":{},"_nodeVersion":"23.2.0","dependencies":{"zod":"^3.22.0","convex":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/satellite-convex_0.3.0_1754159733478_0.3666806570860719","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@6digit/satellite-convex","version":"0.3.1","keywords":["convex","satellite","tools","proxy","local-development","ai","coding-assistant","6digit"],"author":{"name":"6digit"},"license":"MIT","_id":"@6digit/satellite-convex@0.3.1","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"homepage":"https://6digit.studio","bugs":{"url":"https://github.com/6digit/satellite-convex/issues"},"dist":{"shasum":"2e5afce829229ed577efa9e2e2849c5ccffab9a2","tarball":"https://registry.npmjs.org/@6digit/satellite-convex/-/satellite-convex-0.3.1.tgz","fileCount":17,"integrity":"sha512-Huf9TH5IH5qDJ7ytXz15wWPwNQHQ4e3KBwdELz0TB/BcwqbXcCdhaXx/EKwQ1Ri+dDK5i648nx50nzMUxQlsGA==","signatures":[{"sig":"MEYCIQC+Vd9ECHgJZ/Lyas0gUJlYI2YbIcCROG3cjJrwunfeZwIhAOuHIKn8yesP9Y+g+Yq6OZl4L1eNkexZZziS6bvXZHlz","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":40556},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"38aff339f89dd670978d8a4fc90e63723d093e29","scripts":{"dev":"tsx src/index.ts","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"repository":{"url":"git+https://github.com/6digit/satellite-convex.git","type":"git"},"_npmVersion":"11.4.2","description":"Server-side Convex integration for 6digit-satellite with transparent tool proxying and session management","directories":{},"_nodeVersion":"23.2.0","dependencies":{"zod":"^3.22.0","convex":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/satellite-convex_0.3.1_1754162568434_0.7798561284126269","host":"s3://npm-registry-packages-npm-production"}},"0.3.2":{"name":"@6digit/satellite-convex","version":"0.3.2","description":"Server-side Convex integration for 6digit-satellite with transparent tool proxying and session management","main":"dist/index.js","types":"dist/index.d.ts","keywords":["convex","satellite","tools","proxy","local-development","ai","coding-assistant","6digit"],"author":{"name":"6digit"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/6digit/satellite-convex.git"},"homepage":"https://6digit.studio","bugs":{"url":"https://github.com/6digit/satellite-convex/issues"},"scripts":{"build":"tsc","prepublishOnly":"npm run clean && npm run build","dev":"tsx src/index.ts","clean":"rm -rf dist","test":"echo \"Error: no test specified\" && exit 1"},"dependencies":{"convex":"^1.0.0","zod":"^3.22.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.0.0","tsx":"^4.0.0"},"publishConfig":{"access":"public"},"engines":{"node":">=18.0.0"},"_id":"@6digit/satellite-convex@0.3.2","gitHead":"ff036ec2d5d722ac2ddfd4ee9f960e487527f349","_nodeVersion":"23.2.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-aSqFRlM2EdWjbBZVkvZ4ByvkMe8Ekko1bmiSjFp9d1CMggrNtKIT8YCBU/4TJxMnYeNvL711KyjoZthc0G7iIA==","shasum":"842f42e24873af27c9bbfd9fcfaa90cd387166e6","tarball":"https://registry.npmjs.org/@6digit/satellite-convex/-/satellite-convex-0.3.2.tgz","fileCount":17,"unpackedSize":41156,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHI5foAiThaEdF/W7HOrrpt/aRfuPpo+8Pr9MLZSo9AnAiEAiBo682TLSrT7rkAL55sdwjqGm/YBPnfefcY3zpdUVpc="}]},"_npmUser":{"name":"cocporn","email":"cocporn@gmail.com"},"directories":{},"maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/satellite-convex_0.3.2_1755170092708_0.596309709845726"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-26T19:50:17.344Z","modified":"2025-08-14T11:14:53.112Z","0.1.0":"2025-07-26T19:50:17.604Z","0.2.0":"2025-07-27T21:51:39.025Z","0.3.0":"2025-08-02T18:35:33.681Z","0.3.1":"2025-08-02T19:22:48.648Z","0.3.2":"2025-08-14T11:14:52.911Z"},"bugs":{"url":"https://github.com/6digit/satellite-convex/issues"},"author":{"name":"6digit"},"license":"MIT","homepage":"https://6digit.studio","keywords":["convex","satellite","tools","proxy","local-development","ai","coding-assistant","6digit"],"repository":{"type":"git","url":"git+https://github.com/6digit/satellite-convex.git"},"description":"Server-side Convex integration for 6digit-satellite with transparent tool proxying and session management","maintainers":[{"name":"cocporn","email":"cocporn@gmail.com"}],"readme":"# @6digit/satellite-convex\n\nServer-side Convex integration for 6digit-satellite with transparent tool proxying and session management.\n\n## Overview\n\nThe 6digit Satellite Convex package provides server-side utilities for managing satellite connections, pairing, tool invocations, and session persistence in Convex backends. It handles the server-side logic that coordinates with `@6digit/satellite-core` clients.\n\n## Features\n\n- 🔗 **Satellite Registration** - Register satellites and generate pairing codes\n- 🔑 **Pairing Management** - Handle satellite pairing with expiring codes\n- 📡 **Tool Invocation Routing** - Route tool calls to connected satellites\n- 💓 **Session Management** - Track satellite connections and heartbeats\n- 🆔 **Persistent Identity** - Maintain satellite relationships across restarts\n- 🔍 **Status Monitoring** - Query satellite availability and status\n\n## Installation\n\n```bash\nnpm install @6digit/satellite-convex\n```\n\n## Quick Start\n\n```typescript\nimport { SatelliteManager } from '@6digit/satellite-convex';\n\n// In your Convex mutation\nexport const registerSatellite = mutation({\n  args: {\n    satelliteId: v.string(),\n    toolDefinitions: v.array(v.any()),\n    metadata: v.optional(v.any())\n  },\n  handler: async (ctx, args) => {\n    return await SatelliteManager.registerSatellite(\n      ctx,\n      args.satelliteId,\n      args.toolDefinitions,\n      args.metadata\n    );\n  }\n});\n\n// Check if satellite is paired\nexport const isSatellitePaired = query({\n  args: { satelliteId: v.string() },\n  handler: async (ctx, args) => {\n    return await SatelliteManager.isSatellitePaired(ctx, args.satelliteId);\n  }\n});\n```\n\n## Core Components\n\n### SatelliteManager\n\nMain class for managing satellite lifecycle:\n\n```typescript\nclass SatelliteManager {\n  // Register satellite and return pairing code (or null if already paired)\n  static async registerSatellite(ctx, satelliteId, toolDefinitions, metadata?)\n  \n  // Check if satellite is paired\n  static async isSatellitePaired(ctx, satelliteId)\n  \n  // Get satellite status\n  static async getSatelliteStatus(ctx, satelliteId)\n  \n  // Update satellite heartbeat\n  static async updateHeartbeat(ctx, satelliteId)\n  \n  // Disconnect satellite\n  static async disconnectSatellite(ctx, satelliteId)\n}\n```\n\n### Pairing System\n\nSecure pairing with expiring codes:\n\n```typescript\n// Generate human-readable pairing codes\nconst pairingCode = createPairingCode(satelliteId);\n\n// Validate pairing codes\nconst isValid = validatePairingCode(code, satelliteId);\n\n// Check expiration\nconst isExpired = isPairingCodeExpired(pairingCode);\n```\n\n## Database Schema\n\nThe package expects these Convex tables:\n\n```typescript\n// satellites table\n{\n  satelliteId: string,\n  toolDefinitions: any[],\n  status: \"waiting_for_pair\" | \"paired\" | \"connected\" | \"disconnected\",\n  registeredAt: number,\n  lastRegisteredAt?: number,\n  type?: string,\n  name?: string,\n  workingDirectory?: string,\n  platform?: string,\n  nodeVersion?: string\n}\n\n// satelliteSessions table  \n{\n  satelliteId: string,\n  pairingCode: string,\n  connectedAt: number,\n  lastSeen: number,\n  status: \"connected\" | \"disconnected\",\n  name?: string,\n  toolDefinitions: any[]\n}\n\n// pairingCodes table\n{\n  code: string,\n  satelliteId: string,\n  createdAt: number,\n  expiresAt: number,\n  used: boolean\n}\n\n// satelliteToolInvocations table\n{\n  satelliteId: string,\n  toolName: string,\n  parameters: any,\n  status: \"pending\" | \"completed\" | \"failed\",\n  createdAt: number,\n  completedAt?: number,\n  result?: any,\n  error?: string\n}\n```\n\n## Example Convex Functions\n\n```typescript\n// mutations/satellite.ts\nimport { mutation, query } from \"./_generated/server\";\nimport { v } from \"convex/values\";\nimport { SatelliteManager } from \"@6digit/satellite-convex\";\n\nexport const registerSatellite = mutation({\n  args: {\n    satelliteId: v.string(),\n    toolDefinitions: v.array(v.any()),\n    metadata: v.optional(v.any())\n  },\n  handler: async (ctx, args) => {\n    return await SatelliteManager.registerSatellite(\n      ctx,\n      args.satelliteId,\n      args.toolDefinitions,\n      args.metadata\n    );\n  }\n});\n\nexport const updateHeartbeat = mutation({\n  args: { satelliteId: v.string() },\n  handler: async (ctx, args) => {\n    await SatelliteManager.updateHeartbeat(ctx, args.satelliteId);\n  }\n});\n\nexport const getPendingToolInvocations = query({\n  args: { satelliteId: v.string() },\n  handler: async (ctx, args) => {\n    return await ctx.db\n      .query(\"satelliteToolInvocations\")\n      .withIndex(\"by_satellite_id\", (q) => q.eq(\"satelliteId\", args.satelliteId))\n      .filter((q) => q.eq(q.field(\"status\"), \"pending\"))\n      .collect();\n  }\n});\n\nexport const sendToolResult = mutation({\n  args: {\n    invocationId: v.string(),\n    result: v.optional(v.any()),\n    error: v.optional(v.string())\n  },\n  handler: async (ctx, args) => {\n    await ctx.db.patch(args.invocationId, {\n      status: args.error ? \"failed\" : \"completed\",\n      result: args.result,\n      error: args.error,\n      completedAt: Date.now()\n    });\n  }\n});\n```\n\n## Pairing Flow\n\n1. **Satellite Registration**: Satellite calls `registerSatellite` with tools\n2. **Pairing Code Generation**: Server generates human-readable code (e.g., \"BLUE-MOON-42\")\n3. **User Pairing**: User enters code in 6digit Studio interface\n4. **Session Creation**: Server creates persistent session\n5. **Automatic Reconnection**: Subsequent registrations return `null` (already paired)\n\n## Session Management\n\n- **Heartbeats**: Satellites send heartbeats every 30 seconds\n- **Status Tracking**: Server tracks `lastSeen` timestamps\n- **Automatic Cleanup**: Expired sessions can be cleaned up\n- **Reconnection**: Paired satellites automatically reconnect\n\n## License\n\nMIT\n\n## Related Packages\n\n- [`@6digit/satellite-core`](https://npmjs.com/package/@6digit/satellite-core) - Client-side satellite framework\n\n## Contributing\n\nSee [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.\n\n## Support\n\n- 🌐 Website: [6digit.studio](https://6digit.studio)\n- 📧 Issues: [GitHub Issues](https://github.com/6digit/satellite-convex/issues)\n","readmeFilename":"README.md"}