@mentra/sdk 1.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/README.md +102 -0
  2. package/dist/constants/index.d.ts +14 -0
  3. package/dist/constants/index.d.ts.map +1 -0
  4. package/dist/constants/index.js +16 -0
  5. package/dist/examples/rtmp-streaming-example.d.ts +2 -0
  6. package/dist/examples/rtmp-streaming-example.d.ts.map +1 -0
  7. package/dist/examples/rtmp-streaming-example.js +102 -0
  8. package/dist/index.d.ts +4 -0
  9. package/dist/index.d.ts.map +1 -0
  10. package/dist/index.js +33 -0
  11. package/dist/logging/logger.d.ts +3 -0
  12. package/dist/logging/logger.d.ts.map +1 -0
  13. package/dist/logging/logger.js +79 -0
  14. package/dist/tpa/index.d.ts +6 -0
  15. package/dist/tpa/index.d.ts.map +1 -0
  16. package/dist/tpa/index.js +24 -0
  17. package/dist/tpa/server/index.d.ts +193 -0
  18. package/dist/tpa/server/index.d.ts.map +1 -0
  19. package/dist/tpa/server/index.js +436 -0
  20. package/dist/tpa/session/api-client.d.ts +49 -0
  21. package/dist/tpa/session/api-client.d.ts.map +1 -0
  22. package/dist/tpa/session/api-client.js +101 -0
  23. package/dist/tpa/session/dashboard.d.ts +52 -0
  24. package/dist/tpa/session/dashboard.d.ts.map +1 -0
  25. package/dist/tpa/session/dashboard.js +149 -0
  26. package/dist/tpa/session/events.d.ts +178 -0
  27. package/dist/tpa/session/events.d.ts.map +1 -0
  28. package/dist/tpa/session/events.js +294 -0
  29. package/dist/tpa/session/index.d.ts +391 -0
  30. package/dist/tpa/session/index.d.ts.map +1 -0
  31. package/dist/tpa/session/index.js +1452 -0
  32. package/dist/tpa/session/layouts.d.ts +150 -0
  33. package/dist/tpa/session/layouts.d.ts.map +1 -0
  34. package/dist/tpa/session/layouts.js +282 -0
  35. package/dist/tpa/session/modules/streaming.d.ts +100 -0
  36. package/dist/tpa/session/modules/streaming.d.ts.map +1 -0
  37. package/dist/tpa/session/modules/streaming.js +270 -0
  38. package/dist/tpa/session/settings.d.ts +202 -0
  39. package/dist/tpa/session/settings.d.ts.map +1 -0
  40. package/dist/tpa/session/settings.js +361 -0
  41. package/dist/tpa/token/index.d.ts +7 -0
  42. package/dist/tpa/token/index.d.ts.map +1 -0
  43. package/dist/tpa/token/index.js +22 -0
  44. package/dist/tpa/token/utils.d.ts +69 -0
  45. package/dist/tpa/token/utils.d.ts.map +1 -0
  46. package/dist/tpa/token/utils.js +144 -0
  47. package/dist/tpa/webview/index.d.ts +47 -0
  48. package/dist/tpa/webview/index.d.ts.map +1 -0
  49. package/dist/tpa/webview/index.js +344 -0
  50. package/dist/types/dashboard/index.d.ts +128 -0
  51. package/dist/types/dashboard/index.d.ts.map +1 -0
  52. package/dist/types/dashboard/index.js +12 -0
  53. package/dist/types/enums.d.ts +57 -0
  54. package/dist/types/enums.d.ts.map +1 -0
  55. package/dist/types/enums.js +72 -0
  56. package/dist/types/index.d.ts +38 -0
  57. package/dist/types/index.d.ts.map +1 -0
  58. package/dist/types/index.js +87 -0
  59. package/dist/types/layouts.d.ts +51 -0
  60. package/dist/types/layouts.d.ts.map +1 -0
  61. package/dist/types/layouts.js +3 -0
  62. package/dist/types/message-types.d.ts +109 -0
  63. package/dist/types/message-types.d.ts.map +1 -0
  64. package/dist/types/message-types.js +189 -0
  65. package/dist/types/messages/base.d.ts +12 -0
  66. package/dist/types/messages/base.d.ts.map +1 -0
  67. package/dist/types/messages/base.js +3 -0
  68. package/dist/types/messages/cloud-to-glasses.d.ts +126 -0
  69. package/dist/types/messages/cloud-to-glasses.d.ts.map +1 -0
  70. package/dist/types/messages/cloud-to-glasses.js +60 -0
  71. package/dist/types/messages/cloud-to-tpa.d.ts +228 -0
  72. package/dist/types/messages/cloud-to-tpa.d.ts.map +1 -0
  73. package/dist/types/messages/cloud-to-tpa.js +61 -0
  74. package/dist/types/messages/glasses-to-cloud.d.ts +219 -0
  75. package/dist/types/messages/glasses-to-cloud.d.ts.map +1 -0
  76. package/dist/types/messages/glasses-to-cloud.js +88 -0
  77. package/dist/types/messages/tpa-to-cloud.d.ts +146 -0
  78. package/dist/types/messages/tpa-to-cloud.d.ts.map +1 -0
  79. package/dist/types/messages/tpa-to-cloud.js +67 -0
  80. package/dist/types/models.d.ts +165 -0
  81. package/dist/types/models.d.ts.map +1 -0
  82. package/dist/types/models.js +84 -0
  83. package/dist/types/rtmp-stream.d.ts +68 -0
  84. package/dist/types/rtmp-stream.d.ts.map +1 -0
  85. package/dist/types/rtmp-stream.js +3 -0
  86. package/dist/types/streams.d.ts +138 -0
  87. package/dist/types/streams.d.ts.map +1 -0
  88. package/dist/types/streams.js +251 -0
  89. package/dist/types/token.d.ts +41 -0
  90. package/dist/types/token.d.ts.map +1 -0
  91. package/dist/types/token.js +7 -0
  92. package/dist/types/user-session.d.ts +73 -0
  93. package/dist/types/user-session.d.ts.map +1 -0
  94. package/dist/types/user-session.js +17 -0
  95. package/dist/types/webhooks.d.ts +107 -0
  96. package/dist/types/webhooks.d.ts.map +1 -0
  97. package/dist/types/webhooks.js +55 -0
  98. package/dist/utils/resource-tracker.d.ts +94 -0
  99. package/dist/utils/resource-tracker.d.ts.map +1 -0
  100. package/dist/utils/resource-tracker.js +153 -0
  101. package/package.json +50 -0
package/README.md ADDED
@@ -0,0 +1,102 @@
1
+ # @mentra/sdk
2
+
3
+ Build apps for MentraOS smartglasses. This SDK provides everything you need to create real-time smartglasses applications.
4
+
5
+ ## Prerequisites
6
+
7
+ - Node.js (v18 or later)
8
+ - Bun
9
+ - Basic TypeScript knowledge
10
+
11
+ ## ๐Ÿš€ Building Your First App
12
+
13
+ The quickest way to get started is using our example app. This guide assumes you have a pair of [compatible smart glasses](https://mentra.glass/os) connected to a phone running the [MentraOS app](https://mentra.glass/install).
14
+
15
+ ### Install MentraOS on your phone
16
+
17
+ Download MentraOS from [Mentra.glass/install](https://mentra.glass/install)
18
+
19
+ ### Set up ngrok
20
+
21
+ We are going to use ngrok to expose your local app to the internet. This is useful for development, but when you're ready to go live, you'll want to deploy to a cloud service.
22
+
23
+ 1. [Install ngrok](https://ngrok.com/docs/getting-started/)
24
+ 2. Create an ngrok account
25
+ 3. [Set up a static address/URL in the ngrok dashboard](https://dashboard.ngrok.com/)
26
+
27
+ * Make sure you run the `ngrok config add-authtoken <your_authtoken>` line.
28
+ * Make sure you select `Static Domain`, then generate a static domain.
29
+
30
+ <center>
31
+ <img width="75%" src="https://docs.mentra.glass/img/ngrok_guide_1.png"></img>
32
+ </center>
33
+
34
+ ### Register your app with MentraOS
35
+
36
+ ![MentraOS Console](https://imagedelivery.net/nrc8B2Lk8UIoyW7fY8uHVg/560e34ff-c3e6-4e1a-1c4e-a0780e4fcd00/small)
37
+
38
+ 1. Navigate to [console.mentra.glass](https://console.mentra.glass/)
39
+ 2. Click "Sign In" and log in with the same account you're using for MentraOS
40
+ 3. Click "Create App"
41
+ 4. Set a unique package name like `com.yourName.yourAppName`
42
+ 5. For "Public URL", enter your ngrok static URL
43
+ 6. In the edit app screen, add the microphone permission. See the [Permissions](https://docs.mentra.glass/permissions) guide for details.
44
+
45
+ > This automatically installs the app for your user. For other people to test the app (including others in your organization), they need to install the app. Get the app install link from the app edit page under the `Share with Testers` section.
46
+
47
+
48
+ ### Get your app running
49
+
50
+ 1. [Install bun](https://bun.sh/docs/installation)
51
+ 2. Create a new repo from the template using the `Use this template` dropdown in the upper right of [the example app repository](https://github.com/MentraOS-Community/MentraOS-Cloud-Example-App) or the following command:
52
+ ```bash
53
+ gh repo create --template MentraOS-Community/MentraOS-Cloud-Example-App
54
+ ```
55
+
56
+ ![Create repo from template](https://github.com/user-attachments/assets/c10e14e8-2dc5-4dfa-adac-dd334c1b73a5)
57
+
58
+ **Note:** If you want a more in-depth example (recommended for those who've already completed this quickstart), you can use the [Extended Example](https://github.com/MentraOS-Community/MentraOS-Extended-Example-App) which includes app settings support.
59
+ 3. Clone your new repo locally:
60
+ ```bash
61
+ git clone <your-repo-url>
62
+ ```
63
+ 4. Navigate to your repo directory and install dependencies:
64
+ ```bash
65
+ cd <your-repo-name>
66
+ bun install
67
+ ```
68
+ 5. Set up your environment variables:
69
+ * Create a `.env` file in the root directory by copying the example:
70
+ ```bash
71
+ cp .env.example .env
72
+ ```
73
+ * Edit the `.env` file with your app details:
74
+ ```
75
+ PORT=3000
76
+ PACKAGE_NAME=com.yourName.yourAppName
77
+ AUGMENTOS_API_KEY=your_api_key_from_console
78
+ ```
79
+ * Make sure the `PACKAGE_NAME` matches what you registered in the MentraOS Console
80
+ * Get your `API_KEY` from the MentraOS Developer Console
81
+ 6. Run your app:
82
+ ```bash
83
+ bun run dev
84
+ ```
85
+ 7. Expose your app to the internet with ngrok:
86
+ ```bash
87
+ ngrok http --url=<YOUR_NGROK_URL_HERE> 3000
88
+ ```
89
+ Note: `3000` is the port. It must match what is in the app config. If you changed it to `8080`, use `8080` for ngrok instead.
90
+
91
+ > After making changes to your app code or restarting your server, you may need to restart your app inside the MentraOS phone app.
92
+
93
+ For more information, visit the [MentraOS-Cloud-Example-App repository](https://github.com/MentraOS-Community/MentraOS-Cloud-Example-App). For a more in-depth example with app settings support, see the [Extended Example](https://github.com/MentraOS-Community/MentraOS-Extended-Example-App).
94
+
95
+ ## Next Steps
96
+
97
+ - Check out the [documentation](https://docs.mentra.glass) for more information
98
+ - Join our [Discord community](https://discord.gg/5ukNvkEAqT) for help and support
99
+
100
+ ## ๐Ÿ“„ License
101
+
102
+ MIT License.
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Constants for the SDK
3
+ */
4
+ /**
5
+ * System app definitions
6
+ */
7
+ export declare const systemApps: {
8
+ dashboard: {
9
+ name: string;
10
+ packageName: string;
11
+ isSystemApp: boolean;
12
+ };
13
+ };
14
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/constants/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;CAMtB,CAAC"}
@@ -0,0 +1,16 @@
1
+ "use strict";
2
+ /**
3
+ * Constants for the SDK
4
+ */
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.systemApps = void 0;
7
+ /**
8
+ * System app definitions
9
+ */
10
+ exports.systemApps = {
11
+ dashboard: {
12
+ name: 'Dashboard',
13
+ packageName: 'system.augmentos.dashboard',
14
+ isSystemApp: true
15
+ },
16
+ };
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=rtmp-streaming-example.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rtmp-streaming-example.d.ts","sourceRoot":"","sources":["../../src/examples/rtmp-streaming-example.ts"],"names":[],"mappings":""}
@@ -0,0 +1,102 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const session_1 = require("../tpa/session");
4
+ // import type { StreamStatus } from '../tpa/session/modules/streaming';
5
+ // Initialize TPA session
6
+ const session = new session_1.TpaSession({
7
+ packageName: 'com.example.streaming-demo',
8
+ apiKey: 'your-api-key',
9
+ userId: 'example-user@example.com',
10
+ tpaServer: {}, // In a real app, this would be a TpaServer instance
11
+ // In a real app, this would be the production server URL
12
+ augmentOSWebsocketUrl: 'ws://localhost:8002/tpa-ws'
13
+ });
14
+ // Connect to AugmentOS Cloud
15
+ async function startApp() {
16
+ try {
17
+ // Connect with a session ID
18
+ await session.connect('streaming-demo-session');
19
+ console.log('Connected to AugmentOS Cloud');
20
+ // Set up status handler
21
+ setupStreamStatusHandler();
22
+ // Request a stream
23
+ await requestStream();
24
+ // After some time, stop the stream
25
+ setTimeout(stopStream, 60000); // 1 minute
26
+ }
27
+ catch (error) {
28
+ console.error('Error starting app:', error);
29
+ }
30
+ }
31
+ // Set up handler for stream status updates
32
+ function setupStreamStatusHandler() {
33
+ // Register a handler for stream status updates
34
+ const cleanup = session.streaming.onStatus((status) => {
35
+ console.log(`Stream status: ${status.status}`);
36
+ // Log detailed information if available
37
+ if (status.stats) {
38
+ console.log(`Stream stats:
39
+ Bitrate: ${status.stats.bitrate} bps
40
+ FPS: ${status.stats.fps}
41
+ Dropped frames: ${status.stats.droppedFrames}
42
+ Duration: ${status.stats.duration} seconds
43
+ `);
44
+ }
45
+ // Handle different status types
46
+ switch (status.status) {
47
+ case 'initializing':
48
+ console.log('Stream is initializing...');
49
+ break;
50
+ case 'streaming':
51
+ console.log('Stream is actively streaming!');
52
+ break;
53
+ case 'active':
54
+ console.log('Stream is active and running!');
55
+ break;
56
+ case 'error':
57
+ console.error(`Stream error: ${status.errorDetails}`);
58
+ break;
59
+ case 'stopped':
60
+ console.log('Stream has stopped');
61
+ // Clean up resources or update UI as needed
62
+ break;
63
+ }
64
+ });
65
+ // Store the cleanup function somewhere if you need to unregister later
66
+ // For this example, we'll just let it run for the lifetime of the app
67
+ }
68
+ // Request an RTMP stream
69
+ async function requestStream() {
70
+ try {
71
+ // Request a stream with configuration
72
+ await session.streaming.requestStream({
73
+ rtmpUrl: 'rtmp://your-rtmp-server.com/live/stream-key',
74
+ video: {
75
+ width: 1280,
76
+ height: 720,
77
+ bitrate: 1500000, // 1.5 Mbps
78
+ frameRate: 30
79
+ }
80
+ });
81
+ console.log('Stream request sent successfully');
82
+ }
83
+ catch (error) {
84
+ console.error('Error requesting stream:', error);
85
+ }
86
+ }
87
+ // Stop the stream
88
+ async function stopStream() {
89
+ try {
90
+ await session.streaming.stopStream();
91
+ console.log('Stop stream request sent successfully');
92
+ }
93
+ catch (error) {
94
+ console.error('Error stopping stream:', error);
95
+ }
96
+ }
97
+ // Error handling
98
+ session.events.on('error', (error) => {
99
+ console.error('Session error:', error);
100
+ });
101
+ // Start the app
102
+ startApp();
@@ -0,0 +1,4 @@
1
+ export * from "./types";
2
+ export * from "./tpa";
3
+ export * from "./logging/logger";
4
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAA;AACrB,cAAc,kBAAkB,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,33 @@
1
+ "use strict";
2
+ // src/types/index.ts
3
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
4
+ if (k2 === undefined) k2 = k;
5
+ var desc = Object.getOwnPropertyDescriptor(m, k);
6
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
7
+ desc = { enumerable: true, get: function() { return m[k]; } };
8
+ }
9
+ Object.defineProperty(o, k2, desc);
10
+ }) : (function(o, m, k, k2) {
11
+ if (k2 === undefined) k2 = k;
12
+ o[k2] = m[k];
13
+ }));
14
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
15
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
16
+ };
17
+ Object.defineProperty(exports, "__esModule", { value: true });
18
+ // Base exports
19
+ __exportStar(require("./types"), exports);
20
+ __exportStar(require("./tpa"), exports);
21
+ __exportStar(require("./logging/logger"), exports);
22
+ // Model exports
23
+ // export * from './models/user';
24
+ // export * from './models/app';
25
+ // export * from './core/user.session';
26
+ // // Event exports
27
+ // export * from './events/hardware';
28
+ // export * from './layout/layout';
29
+ // export * from './events/phone';
30
+ // // WebSocket exports
31
+ // export * from './websocket/common';
32
+ // export * from './websocket/client';
33
+ // export * from './websocket/tpa';
@@ -0,0 +1,3 @@
1
+ export declare const logger: import("pino").Logger<never, boolean>;
2
+ export default logger;
3
+ //# sourceMappingURL=logger.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logging/logger.ts"],"names":[],"mappings":"AA2EA,eAAO,MAAM,MAAM,uCAAuC,CAAC;AAS3D,eAAe,MAAM,CAAC"}
@@ -0,0 +1,79 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.logger = void 0;
7
+ const pino_1 = __importDefault(require("pino"));
8
+ // Constants and configuration
9
+ const BETTERSTACK_SOURCE_TOKEN = process.env.BETTERSTACK_SOURCE_TOKEN;
10
+ const BETTERSTACK_ENDPOINT = process.env.BETTERSTACK_ENDPOINT || 'https://s1311181.eu-nbg-2.betterstackdata.com';
11
+ const NODE_ENV = process.env.NODE_ENV || 'development';
12
+ const PORTER_APP_NAME = process.env.PORTER_APP_NAME || 'cloud-local';
13
+ // Determine log level based on environment
14
+ const LOG_LEVEL = NODE_ENV === 'production' ? 'info' : 'debug';
15
+ // Setup streams array for Pino multistream
16
+ const streams = [];
17
+ // Use pretty print in development for better readability
18
+ // if (PRETTY_PRINT && NODE_ENV !== 'production') {
19
+ // Pretty transport for development
20
+ const prettyTransport = pino_1.default.transport({
21
+ target: 'pino-pretty',
22
+ options: {
23
+ colorize: true,
24
+ translateTime: 'SYS:standard',
25
+ ignore: 'pid,hostname,env,module,server',
26
+ messageFormat: '{msg}',
27
+ errorProps: '*',
28
+ customPrettifiers: {
29
+ // Add custom prettifiers here if needed
30
+ }
31
+ }
32
+ });
33
+ streams.push({
34
+ stream: prettyTransport,
35
+ level: LOG_LEVEL,
36
+ });
37
+ // } else {
38
+ // // Plain console in production (JSON format)
39
+ // streams.push({
40
+ // stream: process.stdout,
41
+ // level: LOG_LEVEL,
42
+ // });
43
+ // }
44
+ // Add BetterStack transport if token is provided
45
+ if (BETTERSTACK_SOURCE_TOKEN) {
46
+ const betterStackTransport = pino_1.default.transport({
47
+ target: '@logtail/pino',
48
+ options: {
49
+ sourceToken: BETTERSTACK_SOURCE_TOKEN,
50
+ options: { endpoint: BETTERSTACK_ENDPOINT },
51
+ },
52
+ });
53
+ streams.push({
54
+ stream: betterStackTransport,
55
+ level: LOG_LEVEL,
56
+ });
57
+ }
58
+ // Create multistream
59
+ const multistream = pino_1.default.multistream(streams);
60
+ /**
61
+ * Configuration for the root logger
62
+ */
63
+ const baseLoggerOptions = {
64
+ level: LOG_LEVEL,
65
+ base: {
66
+ env: NODE_ENV,
67
+ server: PORTER_APP_NAME,
68
+ },
69
+ timestamp: pino_1.default.stdTimeFunctions.isoTime,
70
+ };
71
+ // Create the root logger with multiple streams
72
+ exports.logger = (0, pino_1.default)(baseLoggerOptions, multistream);
73
+ // Flush logger on process exit
74
+ // process.on('beforeExit', async () => {
75
+ // logger.flush(); // Flush the root logger
76
+ // console.log('Logger flushed before exit');
77
+ // });
78
+ // Default export is the logger
79
+ exports.default = exports.logger;
@@ -0,0 +1,6 @@
1
+ export * from "./server/index";
2
+ export * from "./session/index";
3
+ export * from "./session/settings";
4
+ export * from "./token/index";
5
+ export * from "./webview/index";
6
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tpa/index.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}
@@ -0,0 +1,24 @@
1
+ "use strict";
2
+ // src/index.ts
3
+ // export { TpaSession as TpaClient } from './session';
4
+ // export type { TpaSessionConfig as TpaClientConfig } from './session';
5
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
6
+ if (k2 === undefined) k2 = k;
7
+ var desc = Object.getOwnPropertyDescriptor(m, k);
8
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
9
+ desc = { enumerable: true, get: function() { return m[k]; } };
10
+ }
11
+ Object.defineProperty(o, k2, desc);
12
+ }) : (function(o, m, k, k2) {
13
+ if (k2 === undefined) k2 = k;
14
+ o[k2] = m[k];
15
+ }));
16
+ var __exportStar = (this && this.__exportStar) || function(m, exports) {
17
+ for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
18
+ };
19
+ Object.defineProperty(exports, "__esModule", { value: true });
20
+ __exportStar(require("./server/index"), exports);
21
+ __exportStar(require("./session/index"), exports);
22
+ __exportStar(require("./session/settings"), exports);
23
+ __exportStar(require("./token/index"), exports);
24
+ __exportStar(require("./webview/index"), exports);
@@ -0,0 +1,193 @@
1
+ /**
2
+ * ๐Ÿš€ TPA Server Module
3
+ *
4
+ * Creates and manages a server for Third Party Apps (TPAs) in the AugmentOS ecosystem.
5
+ * Handles webhook endpoints, session management, and cleanup.
6
+ */
7
+ import { type Express } from 'express';
8
+ import { TpaSession } from '../session';
9
+ import { ToolCall } from '../../types';
10
+ import { Logger } from 'pino';
11
+ /**
12
+ * ๐Ÿ”ง Configuration options for TPA Server
13
+ *
14
+ * @example
15
+ * ```typescript
16
+ * const config: TpaServerConfig = {
17
+ * packageName: 'org.example.myapp',
18
+ * apiKey: 'your_api_key',
19
+ * port: 7010,
20
+ * publicDir: './public'
21
+ * };
22
+ * ```
23
+ */
24
+ export interface TpaServerConfig {
25
+ /** ๐Ÿ“ฆ Unique identifier for your TPA (e.g., 'org.company.appname') must match what you specified at https://console.mentra.glass */
26
+ packageName: string;
27
+ /** ๐Ÿ”‘ API key for authentication with AugmentOS Cloud */
28
+ apiKey: string;
29
+ /** ๐ŸŒ Port number for the server (default: 7010) */
30
+ port?: number;
31
+ /** ๐Ÿ›ฃ๏ธ [DEPRECATED] do not set: The SDK will automatically expose an endpoint at '/webhook' */
32
+ webhookPath?: string;
33
+ /**
34
+ * ๐Ÿ“‚ Directory for serving static files (e.g., images, logos)
35
+ * Set to false to disable static file serving
36
+ */
37
+ publicDir?: string | false;
38
+ /** โค๏ธ Enable health check endpoint at /health (default: true) */
39
+ healthCheck?: boolean;
40
+ /**
41
+ * ๐Ÿ” Secret key used to sign session cookies
42
+ * This must be a strong, unique secret
43
+ */
44
+ cookieSecret?: string;
45
+ /** TPA instructions string shown to the user */
46
+ tpaInstructions?: string;
47
+ }
48
+ /**
49
+ * ๐ŸŽฏ TPA Server Implementation
50
+ *
51
+ * Base class for creating TPA servers. Handles:
52
+ * - ๐Ÿ”„ Session lifecycle management
53
+ * - ๐Ÿ“ก Webhook endpoints for AugmentOS Cloud
54
+ * - ๐Ÿ“‚ Static file serving
55
+ * - โค๏ธ Health checks
56
+ * - ๐Ÿงน Cleanup on shutdown
57
+ *
58
+ * @example
59
+ * ```typescript
60
+ * class MyAppServer extends TpaServer {
61
+ * protected async onSession(session: TpaSession, sessionId: string, userId: string) {
62
+ * // Handle new user sessions here
63
+ * session.events.onTranscription((data) => {
64
+ * session.layouts.showTextWall(data.text);
65
+ * });
66
+ * }
67
+ * }
68
+ *
69
+ * const server = new MyAppServer({
70
+ * packageName: 'org.example.myapp',
71
+ * apiKey: 'your_api_key',
72
+ * publicDir: "/public",
73
+ * });
74
+ *
75
+ * await server.start();
76
+ * ```
77
+ */
78
+ export declare class TpaServer {
79
+ private config;
80
+ /** Express app instance */
81
+ private app;
82
+ /** Map of active user sessions by sessionId */
83
+ private activeSessions;
84
+ /** Array of cleanup handlers to run on shutdown */
85
+ private cleanupHandlers;
86
+ /** TPA instructions string shown to the user */
87
+ private tpaInstructions;
88
+ readonly logger: Logger;
89
+ constructor(config: TpaServerConfig);
90
+ getExpressApp(): Express;
91
+ /**
92
+ * ๐Ÿ‘ฅ Session Handler
93
+ * Override this method to handle new TPA sessions.
94
+ * This is where you implement your app's core functionality.
95
+ *
96
+ * @param session - TPA session instance for the user
97
+ * @param sessionId - Unique identifier for this session
98
+ * @param userId - User's identifier
99
+ */
100
+ protected onSession(session: TpaSession, sessionId: string, userId: string): Promise<void>;
101
+ /**
102
+ * ๐Ÿ‘ฅ Stop Handler
103
+ * Override this method to handle stop requests.
104
+ * This is where you can clean up resources when a session is stopped.
105
+ *
106
+ * @param sessionId - Unique identifier for this session
107
+ * @param userId - User's identifier
108
+ * @param reason - Reason for stopping
109
+ */
110
+ protected onStop(sessionId: string, userId: string, reason: string): Promise<void>;
111
+ /**
112
+ * ๐Ÿ› ๏ธ Tool Call Handler
113
+ * Override this method to handle tool calls from AugmentOS Cloud.
114
+ * This is where you implement your app's tool functionality.
115
+ *
116
+ * @param toolCall - The tool call request containing tool details and parameters
117
+ * @returns Optional string response that will be sent back to AugmentOS Cloud
118
+ */
119
+ protected onToolCall(toolCall: ToolCall): Promise<string | undefined>;
120
+ /**
121
+ * ๐Ÿš€ Start the Server
122
+ * Starts listening for incoming connections and webhook calls.
123
+ *
124
+ * @returns Promise that resolves when server is ready
125
+ */
126
+ start(): Promise<void>;
127
+ /**
128
+ * ๐Ÿ›‘ Stop the Server
129
+ * Gracefully shuts down the server and cleans up all sessions.
130
+ */
131
+ stop(): void;
132
+ /**
133
+ * ๐Ÿ” Generate a TPA token for a user
134
+ * This should be called when handling a session webhook request.
135
+ *
136
+ * @param userId - User identifier
137
+ * @param sessionId - Session identifier
138
+ * @param secretKey - Secret key for signing the token
139
+ * @returns JWT token string
140
+ */
141
+ protected generateToken(userId: string, sessionId: string, secretKey: string): string;
142
+ /**
143
+ * ๐Ÿงน Add Cleanup Handler
144
+ * Register a function to be called during server shutdown.
145
+ *
146
+ * @param handler - Function to call during cleanup
147
+ */
148
+ protected addCleanupHandler(handler: () => void): void;
149
+ /**
150
+ * ๐ŸŽฏ Setup Webhook Endpoint
151
+ * Creates the webhook endpoint that AugmentOS Cloud calls to start new sessions.
152
+ */
153
+ private setupWebhook;
154
+ /**
155
+ * ๐Ÿ› ๏ธ Setup Tool Call Endpoint
156
+ * Creates a /tool endpoint for handling tool calls from AugmentOS Cloud.
157
+ */
158
+ private setupToolCallEndpoint;
159
+ /**
160
+ * Handle a session request webhook
161
+ */
162
+ private handleSessionRequest;
163
+ /**
164
+ * Handle a stop request webhook
165
+ */
166
+ private handleStopRequest;
167
+ /**
168
+ * โค๏ธ Setup Health Check Endpoint
169
+ * Creates a /health endpoint for monitoring server status.
170
+ */
171
+ private setupHealthCheck;
172
+ /**
173
+ * โš™๏ธ Setup Settings Endpoint
174
+ * Creates a /settings endpoint that the AugmentOS Cloud can use to update settings.
175
+ */
176
+ private setupSettingsEndpoint;
177
+ /**
178
+ * ๐Ÿ“‚ Setup Static File Serving
179
+ * Configures Express to serve static files from the specified directory.
180
+ */
181
+ private setupPublicDir;
182
+ /**
183
+ * ๐Ÿ›‘ Setup Shutdown Handlers
184
+ * Registers process signal handlers for graceful shutdown.
185
+ */
186
+ private setupShutdown;
187
+ /**
188
+ * ๐Ÿงน Cleanup
189
+ * Closes all active sessions and runs cleanup handlers.
190
+ */
191
+ private cleanup;
192
+ }
193
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tpa/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAgB,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAEhD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,OAAO,EAQL,QAAQ,EACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAI9B;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,oIAAoI;IACpI,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAE3B,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,SAAS;IAYR,OAAO,CAAC,MAAM;IAX1B,2BAA2B;IAC3B,OAAO,CAAC,GAAG,CAAU;IACrB,+CAA+C;IAC/C,OAAO,CAAC,cAAc,CAAiC;IACvD,mDAAmD;IACnD,OAAO,CAAC,eAAe,CAAyB;IAChD,gDAAgD;IAChD,OAAO,CAAC,eAAe,CAAuB;IAE9C,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEX,MAAM,EAAE,eAAe;IAuCpC,aAAa,IAAI,OAAO;IAI/B;;;;;;;;OAQG;cACa,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhG;;;;;;;;OAQG;cACa,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxF;;;;;;;OAOG;cACa,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAM3E;;;;;OAKG;IACI,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAY7B;;;OAGG;IACI,IAAI,IAAI,IAAI;IAMnB;;;;;;;;KAQC;IACD,SAAS,CAAC,aAAa,CACrB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,MAAM;IAYT;;;;;OAKG;IACH,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAItD;;;OAGG;IACH,OAAO,CAAC,YAAY;IAoCpB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IA2B7B;;OAEG;YACW,oBAAoB;IA6DlC;;OAEG;YACW,iBAAiB;IAgB/B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAyD7B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAQtB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAKrB;;;OAGG;IACH,OAAO,CAAC,OAAO;CAWhB"}