skedyul 0.2.147 → 0.2.149

package/dist/.build-stamp

@@ -1 +1 @@
-1770681945679
+1770690573798

package/dist/errors.d.ts

@@ -75,3 +75,26 @@ export declare class InvalidConfigurationError extends InstallError {
 export declare class ConnectionError extends InstallError {
     constructor(message?: string);
 }
+/**
+ * Error thrown when app authentication/authorization is invalid and needs re-validation.
+ *
+ * Any app integration can throw this error to signal that the installation's
+ * auth status should be set to INVALID, triggering re-authorization flow.
+ *
+ * The error code 'APP_AUTH_INVALID' is used by the workflow to detect and handle
+ * this error generically, regardless of which app throws it.
+ *
+ * The redirect URL is constructed by the workflow after catching this error,
+ * so apps don't need to provide it.
+ *
+ * @example
+ * ```typescript
+ * if (tokenExpired) {
+ *   throw new AppAuthInvalidError('Access token has expired. Please re-authorize the app.')
+ * }
+ * ```
+ */
+export declare class AppAuthInvalidError extends Error {
+    readonly code = "APP_AUTH_INVALID";
+    constructor(message: string);
+}

package/dist/errors.js

@@ -7,7 +7,7 @@
  * that the frontend can display inline on the install form.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ConnectionError = exports.InvalidConfigurationError = exports.AuthenticationError = exports.MissingRequiredFieldError = exports.InstallError = void 0;
+exports.AppAuthInvalidError = exports.ConnectionError = exports.InvalidConfigurationError = exports.AuthenticationError = exports.MissingRequiredFieldError = exports.InstallError = void 0;
 /**
  * Base error class for install handler errors.
  *
@@ -97,3 +97,30 @@ class ConnectionError extends InstallError {
     }
 }
 exports.ConnectionError = ConnectionError;
+/**
+ * Error thrown when app authentication/authorization is invalid and needs re-validation.
+ *
+ * Any app integration can throw this error to signal that the installation's
+ * auth status should be set to INVALID, triggering re-authorization flow.
+ *
+ * The error code 'APP_AUTH_INVALID' is used by the workflow to detect and handle
+ * this error generically, regardless of which app throws it.
+ *
+ * The redirect URL is constructed by the workflow after catching this error,
+ * so apps don't need to provide it.
+ *
+ * @example
+ * ```typescript
+ * if (tokenExpired) {
+ *   throw new AppAuthInvalidError('Access token has expired. Please re-authorize the app.')
+ * }
+ * ```
+ */
+class AppAuthInvalidError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'APP_AUTH_INVALID';
+        this.name = 'AppAuthInvalidError';
+    }
+}
+exports.AppAuthInvalidError = AppAuthInvalidError;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { ToolResponseMetaSchema } from './types';
 export * from './schemas';
 export { server } from './server';
 export { DEFAULT_DOCKERFILE } from './dockerfile';
-export { InstallError, MissingRequiredFieldError, AuthenticationError, InvalidConfigurationError, ConnectionError, } from './errors';
+export { InstallError, MissingRequiredFieldError, AuthenticationError, InvalidConfigurationError, ConnectionError, AppAuthInvalidError, } from './errors';
 export type { InstallErrorCode } from './errors';
 export { z };
 export { workplace, communicationChannel, instance, token, file, webhook, resource, contactAssociationLink, configure, getConfig, runWithConfig, } from './core/client';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRequiredInstallEnvKeys = exports.getAllEnvKeys = exports.CONFIG_FILE_NAMES = exports.validateConfig = exports.loadConfig = exports.defineConfig = exports.runWithConfig = exports.getConfig = exports.configure = exports.contactAssociationLink = exports.resource = exports.webhook = exports.file = exports.token = exports.instance = exports.communicationChannel = exports.workplace = exports.z = exports.ConnectionError = exports.InvalidConfigurationError = exports.AuthenticationError = exports.MissingRequiredFieldError = exports.InstallError = exports.DEFAULT_DOCKERFILE = exports.server = exports.ToolResponseMetaSchema = void 0;
+exports.getRequiredInstallEnvKeys = exports.getAllEnvKeys = exports.CONFIG_FILE_NAMES = exports.validateConfig = exports.loadConfig = exports.defineConfig = exports.runWithConfig = exports.getConfig = exports.configure = exports.contactAssociationLink = exports.resource = exports.webhook = exports.file = exports.token = exports.instance = exports.communicationChannel = exports.workplace = exports.z = exports.AppAuthInvalidError = exports.ConnectionError = exports.InvalidConfigurationError = exports.AuthenticationError = exports.MissingRequiredFieldError = exports.InstallError = exports.DEFAULT_DOCKERFILE = exports.server = exports.ToolResponseMetaSchema = void 0;
 const zod_1 = require("zod");
 Object.defineProperty(exports, "z", { enumerable: true, get: function () { return zod_1.z; } });
 __exportStar(require("./types"), exports);
@@ -32,6 +32,7 @@ Object.defineProperty(exports, "MissingRequiredFieldError", { enumerable: true,
 Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_1.AuthenticationError; } });
 Object.defineProperty(exports, "InvalidConfigurationError", { enumerable: true, get: function () { return errors_1.InvalidConfigurationError; } });
 Object.defineProperty(exports, "ConnectionError", { enumerable: true, get: function () { return errors_1.ConnectionError; } });
+Object.defineProperty(exports, "AppAuthInvalidError", { enumerable: true, get: function () { return errors_1.AppAuthInvalidError; } });
 var client_1 = require("./core/client");
 Object.defineProperty(exports, "workplace", { enumerable: true, get: function () { return client_1.workplace; } });
 Object.defineProperty(exports, "communicationChannel", { enumerable: true, get: function () { return client_1.communicationChannel; } });

package/dist/server.js

@@ -403,6 +403,24 @@ function createCallToolHandler(registry, state, onMaxRequests) {
             };
         }
         catch (error) {
+            // Check if it's an AppAuthInvalidError
+            if (error instanceof errors_1.AppAuthInvalidError) {
+                return {
+                    output: null,
+                    billing: { credits: 0 },
+                    meta: {
+                        success: false,
+                        message: error.message,
+                        toolName,
+                    },
+                    error: {
+                        code: error.code,
+                        message: error.message,
+                    },
+                    // Note: redirect URL will be added by workflow after detecting APP_AUTH_INVALID
+                };
+            }
+            // Generic error handling for other errors
             const errorMessage = error instanceof Error ? error.message : String(error ?? '');
             return {
                 output: null,
@@ -412,7 +430,10 @@ function createCallToolHandler(registry, state, onMaxRequests) {
                     message: errorMessage,
                     toolName,
                 },
-                error: errorMessage,
+                error: {
+                    code: 'TOOL_EXECUTION_ERROR',
+                    message: errorMessage,
+                },
             };
         }
         finally {
@@ -878,49 +899,37 @@ function createDedicatedServerInstance(config, tools, callTool, state, mcpServer
                 }
                 return;
             }
-            // Handle /oauth_callback endpoint for OAuth callbacks (called by platform route)
-            if (pathname === '/oauth_callback' && req.method === 'GET') {
+            // Handle /oauth_callback endpoint for OAuth callbacks (called by Temporal workflow)
+            if (pathname === '/oauth_callback' && req.method === 'POST') {
                 if (!config.hooks?.oauth_callback) {
-                    sendHTML(res, 404, '<html><body><h1>OAuth callback handler not configured</h1></body></html>');
+                    sendJSON(res, 404, { error: 'OAuth callback handler not configured' });
                     return;
                 }
-                // Parse query parameters
-                const url = new URL(req.url || '', `http://${req.headers.host}`);
-                const query = {};
-                url.searchParams.forEach((value, key) => {
-                    query[key] = value;
-                });
-                // Decode state parameter (contains appInstallationId, workplace, app info)
-                let stateData = {};
-                if (query.state) {
-                    try {
-                        stateData = JSON.parse(Buffer.from(query.state, 'base64').toString('utf-8'));
-                    }
-                    catch {
-                        sendHTML(res, 400, '<html><body><h1>Invalid state parameter</h1></body></html>');
-                        return;
-                    }
+                let oauthCallbackBody = {};
+                try {
+                    oauthCallbackBody = (await parseJSONBody(req));
                 }
-                if (!stateData.appInstallationId || !stateData.workplace || !stateData.app) {
-                    sendHTML(res, 400, '<html><body><h1>Missing required state data</h1></body></html>');
+                catch {
+                    sendJSON(res, 400, {
+                        error: { code: -32700, message: 'Parse error' },
+                    });
+                    return;
+                }
+                if (!oauthCallbackBody.query) {
+                    sendJSON(res, 400, {
+                        error: { code: -32602, message: 'Missing query parameter' },
+                    });
                     return;
                 }
-                // Get current env vars from request (if any)
-                // For OAuth callbacks, we might not have env vars yet, so use empty object
-                const env = {};
-                const oauthCallbackContext = {
-                    query,
-                    env,
-                    workplace: stateData.workplace,
-                    appInstallationId: stateData.appInstallationId,
-                    app: stateData.app,
-                };
                 // Build request-scoped config for SDK access
-                // Use env from process or request if available
+                // Use provision-level token from process.env (baked at provisioning time)
                 const oauthCallbackRequestConfig = {
                     baseUrl: process.env.SKEDYUL_API_URL ?? '',
                     apiToken: process.env.SKEDYUL_API_TOKEN ?? '',
                 };
+                const oauthCallbackContext = {
+                    query: oauthCallbackBody.query,
+                };
                 try {
                     const oauthCallbackHook = config.hooks.oauth_callback;
                     const oauthCallbackHandler = typeof oauthCallbackHook === 'function'
@@ -929,29 +938,19 @@ function createDedicatedServerInstance(config, tools, callTool, state, mcpServer
                     const result = await (0, client_1.runWithConfig)(oauthCallbackRequestConfig, async () => {
                         return await oauthCallbackHandler(oauthCallbackContext);
                     });
-                    // Return custom HTML if provided, otherwise default success page
-                    const html = result.html ?? `
-            <html>
-              <body style="font-family: system-ui; padding: 40px; text-align: center;">
-                <h1 style="color: #38a169;">✓ Authorization Successful</h1>
-                <p>You can close this window and return to the app.</p>
-              </body>
-            </html>
-          `;
-                    sendHTML(res, 200, html);
+                    sendJSON(res, 200, {
+                        appInstallationId: result.appInstallationId,
+                        env: result.env ?? {},
+                    });
                 }
                 catch (err) {
                     const errorMessage = err instanceof Error ? err.message : String(err ?? 'Unknown error');
-                    const errorHtml = `
-            <html>
-              <body style="font-family: system-ui; padding: 40px; text-align: center;">
-                <h1 style="color: #e53e3e;">Authorization Failed</h1>
-                <p>${errorMessage}</p>
-                <p>You can close this window.</p>
-              </body>
-            </html>
-          `;
-                    sendHTML(res, 500, errorHtml);
+                    sendJSON(res, 500, {
+                        error: {
+                            code: -32603,
+                            message: errorMessage,
+                        },
+                    });
                 }
                 return;
             }
@@ -1573,47 +1572,29 @@ function createServerlessInstance(config, tools, callTool, state, mcpServer, reg
                     }
                 }
                 // Handle /oauth_callback endpoint for OAuth callbacks (called by platform route)
-                if (path === '/oauth_callback' && method === 'GET') {
+                if (path === '/oauth_callback' && method === 'POST') {
                     if (!config.hooks?.oauth_callback) {
-                        return createResponse(404, { error: 'OAuth callback handler not configured' }, { ...headers, 'Content-Type': 'text/html; charset=utf-8' });
+                        return createResponse(404, { error: 'OAuth callback handler not configured' }, headers);
                     }
-                    // Parse query parameters from event
-                    const query = {};
-                    if (event.queryStringParameters) {
-                        Object.entries(event.queryStringParameters).forEach(([key, value]) => {
-                            if (value)
-                                query[key] = value;
-                        });
+                    let oauthCallbackBody = {};
+                    try {
+                        oauthCallbackBody = event.body ? JSON.parse(event.body) : {};
                     }
-                    // Decode state parameter (contains appInstallationId, workplace, app info)
-                    let stateData = {};
-                    if (query.state) {
-                        try {
-                            stateData = JSON.parse(Buffer.from(query.state, 'base64').toString('utf-8'));
-                        }
-                        catch {
-                            return createResponse(400, { error: 'Invalid state parameter' }, { ...headers, 'Content-Type': 'text/html; charset=utf-8' });
-                        }
+                    catch {
+                        return createResponse(400, { error: { code: -32700, message: 'Parse error' } }, headers);
                     }
-                    if (!stateData.appInstallationId || !stateData.workplace || !stateData.app) {
-                        return createResponse(400, { error: 'Missing required state data' }, { ...headers, 'Content-Type': 'text/html; charset=utf-8' });
+                    if (!oauthCallbackBody.query) {
+                        return createResponse(400, { error: { code: -32602, message: 'Missing query parameter' } }, headers);
                     }
-                    // Get current env vars from request (if any)
-                    // For OAuth callbacks, we might not have env vars yet, so use empty object
-                    const env = {};
-                    const oauthCallbackContext = {
-                        query,
-                        env,
-                        workplace: stateData.workplace,
-                        appInstallationId: stateData.appInstallationId,
-                        app: stateData.app,
-                    };
                     // Build request-scoped config for SDK access
-                    // Use env from process or request if available
+                    // Use provision-level token from process.env (baked at provisioning time)
                     const oauthCallbackRequestConfig = {
                         baseUrl: process.env.SKEDYUL_API_URL ?? '',
                         apiToken: process.env.SKEDYUL_API_TOKEN ?? '',
                     };
+                    const oauthCallbackContext = {
+                        query: oauthCallbackBody.query,
+                    };
                     try {
                         const oauthCallbackHook = config.hooks.oauth_callback;
                         const oauthCallbackHandler = typeof oauthCallbackHook === 'function'
@@ -1622,29 +1603,19 @@ function createServerlessInstance(config, tools, callTool, state, mcpServer, reg
                         const result = await (0, client_1.runWithConfig)(oauthCallbackRequestConfig, async () => {
                             return await oauthCallbackHandler(oauthCallbackContext);
                         });
-                        // Return custom HTML if provided, otherwise default success page
-                        const html = result.html ?? `
-              <html>
-                <body style="font-family: system-ui; padding: 40px; text-align: center;">
-                  <h1 style="color: #38a169;">✓ Authorization Successful</h1>
-                  <p>You can close this window and return to the app.</p>
-                </body>
-              </html>
-            `;
-                        return createResponse(200, html, { ...headers, 'Content-Type': 'text/html; charset=utf-8' });
+                        return createResponse(200, {
+                            appInstallationId: result.appInstallationId,
+                            env: result.env ?? {},
+                        }, headers);
                     }
                     catch (err) {
                         const errorMessage = err instanceof Error ? err.message : String(err ?? 'Unknown error');
-                        const errorHtml = `
-              <html>
-                <body style="font-family: system-ui; padding: 40px; text-align: center;">
-                  <h1 style="color: #e53e3e;">Authorization Failed</h1>
-                  <p>${errorMessage}</p>
-                  <p>You can close this window.</p>
-                </body>
-              </html>
-            `;
-                        return createResponse(500, errorHtml, { ...headers, 'Content-Type': 'text/html; charset=utf-8' });
+                        return createResponse(500, {
+                            error: {
+                                code: -32603,
+                                message: errorMessage,
+                            },
+                        }, headers);
                     }
                 }
                 if (path === '/health' && method === 'GET') {

package/dist/types.d.ts

@@ -104,6 +104,14 @@ export interface ToolEffect {
     /** URL to navigate to after the tool completes */
     redirect?: string;
 }
+/**
+ * Structured error information for tool execution results.
+ * Uses codes for serialization and workflow detection.
+ */
+export interface ToolError {
+    code: string;
+    message: string;
+}
 export interface ToolExecutionResult<Output = unknown> {
     /** Tool-specific output data. Null on error. */
     output: Output | null;
@@ -113,6 +121,8 @@ export interface ToolExecutionResult<Output = unknown> {
     meta: ToolResponseMeta;
     /** Optional client-side effects to execute */
     effect?: ToolEffect;
+    /** Structured error information (null/undefined if no error) */
+    error?: ToolError | null;
 }
 export interface ToolSchemaWithJson<Schema extends z.ZodTypeAny = z.ZodTypeAny> {
     zod: Schema;
@@ -265,22 +275,10 @@ export type InstallHandlerResult<Hooks extends ServerHooks = ServerHooks> = HasO
 export type InstallHandler<Hooks extends ServerHooks = ServerHooks> = (ctx: InstallHandlerContext) => Promise<InstallHandlerResult<Hooks>>;
 export interface OAuthCallbackContext {
     query: Record<string, string>;
-    env: Record<string, string>;
-    workplace: {
-        id: string;
-        subdomain: string;
-    };
-    appInstallationId: string;
-    app: {
-        id: string;
-        versionId: string;
-        handle: string;
-        versionHandle: string;
-    };
 }
 export interface OAuthCallbackResult {
     env?: Record<string, string>;
-    html?: string;
+    appInstallationId?: string;
 }
 export type OAuthCallbackHandler = (ctx: OAuthCallbackContext) => Promise<OAuthCallbackResult>;
 export interface ProvisionHandlerContext {
@@ -312,7 +310,7 @@ export interface ToolCallResponse {
     output: unknown | null;
     billing: BillingInfo;
     meta: ToolResponseMeta;
-    error?: string;
+    error?: ToolError | null;
     effect?: ToolEffect;
 }
 export interface DedicatedServerInstance {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skedyul",
-  "version": "0.2.147",
+  "version": "0.2.149",
   "description": "The Skedyul SDK for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",