@stepper-io/core 1.0.0 → 1.1.0

package/dist/index.d.mts

@@ -99,6 +99,13 @@ interface EmbeddedInputField extends Omit<BaseInputField, 'create'> {
     create?: {
         action: string;
     };
+    /**
+     * When true (the default), the editor asks the user to pick one of their own
+     * connections before rendering the embed, so another user's token is never
+     * inlined into the embedded HTML. Set false to use the step's configured
+     * connection instead.
+     */
+    chooseConnection?: boolean;
 }
 interface ObjectValue {
     [key: string]: any;
@@ -195,6 +202,30 @@ type API = {
     put: RequestClient;
     delete: RequestClient;
     callbackUrl: () => Promise<string>;
+    /**
+     * Returns credentials whose access token is usable for the next few minutes.
+     *
+     * Use this from embedded fields or server-rendered surfaces that need an
+     * access token at render time and can't react to a 401 the way an in-action
+     * HTTP call can. Repeated calls within a single resolution pass return a
+     * stable result so embedded HTML doesn't churn.
+     *
+     * SECURITY: only `access_token` (plus its `expires_at`) is returned — never
+     * the refresh_token or other credential fields — so a stray
+     * `JSON.stringify(credentials)` in rendered output can't leak a long-lived
+     * token. Still, only ever interpolate `credentials.access_token`.
+     *
+     * NOTE: near expiry this throws StaleAuthenticationError to ride the
+     * dispatcher's refresh-and-retry flow. That recovery works on paths that
+     * serialize errors into an ActionResult (action/trigger parameter resolution,
+     * embedded fields, and dropdown options resolvers).
+     */
+    getFreshCredentials: () => Promise<{
+        credentials: {
+            access_token: string;
+            expires_at?: number;
+        };
+    }>;
     notificationUrl: () => Promise<{
         success: string;
         failure: string;
@@ -258,12 +289,62 @@ type ErrorTypes = typeof UnknownError | typeof NonRetryableError | typeof RateLi
 type Input = {
     [key: string]: any;
 };
+/**
+ * Levels for logger entries emitted via `ctx.logger`. Mirrors the standard
+ * console levels.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * A single structured log entry captured during an invocation.
+ */
+interface LogEntry {
+    level: LogLevel;
+    /** ISO-8601 timestamp at which the entry was emitted. */
+    timestamp: string;
+    message: string;
+    /** Optional structured payload accompanying the message. */
+    data?: any;
+    /** Origin of the entry: `'app'` for user-emitted, `'http'` for auto-captured request/response traces. */
+    source: 'app' | 'http';
+}
+/**
+ * Lightweight logger exposed to action and trigger handlers via `ctx.logger`.
+ *
+ * Captured entries are returned in the invocation response and persisted to
+ * the per-version test execution log when the app version is not live. Live
+ * runs receive a no-op logger — logger calls are safe but produce no output.
+ *
+ * Example:
+ * ```ts
+ * ctx.logger.info('starting sync', { since: cursor });
+ * ctx.logger.debug('intermediate step', { rows: 42 });
+ * ```
+ */
+interface Logger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    /**
+     * Internal: append a structured entry with an explicit `source`. Used by
+     * the runtime's HTTP request/response tracer to record `source: 'http'`
+     * entries. App authors should use `info`/`debug`/`warn`/`error` instead.
+     */
+    appendEntry?(entry: Omit<LogEntry, 'timestamp'>): void;
+}
 type Context<TInput extends Input = Input> = {
     input: TInput;
     env: any;
     auth: any;
     app: StepperApp;
     api: API;
+    /**
+     * Optional logger for capturing structured entries during the invocation.
+     * The runtime injects a `NoopLogger` for live versions and a `CaptureLogger`
+     * for non-live (test) versions. App authors can call `ctx.logger?.info(...)`
+     * unconditionally — when undefined or noop, calls are a no-op.
+     */
+    logger?: Logger;
     metadata?: ContextMetadata;
 };
 type ContextMetadata = {
@@ -458,6 +539,13 @@ interface StepperApp {
     platformVersion: string;
     authentication: Authentication;
     isPlatformApp?: boolean;
+    /**
+     * Marks an externally-authored, team-owned app. Set automatically by the
+     * dispatcher at deploy time — do NOT set manually; any author value is
+     * overridden. Absent on Stepper-managed apps. Used by the runtime to gate
+     * features for private team apps.
+     */
+    isExternalTeamApp?: boolean;
     actions: Action[] | ((context: Context) => Promise<Action[]> | Action[]);
     triggers: Trigger[] | ((context: Context) => Promise<Trigger[]> | Trigger[]);
     globalWebhooks?: GlobalWebhook[];
@@ -525,4 +613,4 @@ declare class ForbiddenError extends HTTPError {
     static is(error: unknown): error is ForbiddenError;
 }
 
-export { type API, type Action, type AppDependenciesMap, type Authentication, BadRequestError, BaseError, type BasicAuthentication, type BearerAuthentication, type Callable, type CallableList, type ClientErrorStatusCode, type ContentfulStatusCode, type ContentlessStatusCode, type Context, type ContextMetadata, CriticalAuthenticationError, type CustomAuthentication, type DependencyInfo, type DeprecatedStatusCode, type DescribeResponse, type Descriptions, type DropdownInputFieldMultipleValue, type DropdownInputFieldSingleValue, type DropdownOption, type DynamicList, type EmbeddedInputField, type ErrorField, type ErrorType, type ErrorTypes, type FlowRequestConfiguration, ForbiddenError, type GlobalWebhook, type GlobalWebhookEvent, type GlobalWebhookResponse, HTTPError, HTTPNotFoundError, type HTTPStatusCode, type InfoStatusCode, type Input, type InputField, type InputFields, type Invoke, type ManualTrigger, type MessageField, NonRetryableError, type NoneAuthentication, NotFoundError, type OAuth2Authentication, type ObjectInputField, type PaginatedResponse, type PollingTrigger, RateLimitHitError, type RedirectStatusCode, type RefInputField, type RequestClient, type RequestMiddleware, type SchemaInputField, type ServerErrorStatusCode, StaleAuthenticationError, type StatusCode, type StepperApp, type SubscriptionOptionFilter, type SubscriptionOptions, type SuccessStatusCode, type TemporaryFile, type Trigger, UnauthorizedError, UnknownError, type UnofficialStatusCode, UnprocessableEntityError, type WebhookBaseTrigger, type WebhookPayload, type WebhookPollSourceTrigger, type WebhookSourceTrigger, type WebhookTrigger, action, app, authentication, trigger };
+export { type API, type Action, type AppDependenciesMap, type Authentication, BadRequestError, BaseError, type BasicAuthentication, type BearerAuthentication, type Callable, type CallableList, type ClientErrorStatusCode, type ContentfulStatusCode, type ContentlessStatusCode, type Context, type ContextMetadata, CriticalAuthenticationError, type CustomAuthentication, type DependencyInfo, type DeprecatedStatusCode, type DescribeResponse, type Descriptions, type DropdownInputFieldMultipleValue, type DropdownInputFieldSingleValue, type DropdownOption, type DynamicList, type EmbeddedInputField, type ErrorField, type ErrorType, type ErrorTypes, type FlowRequestConfiguration, ForbiddenError, type GlobalWebhook, type GlobalWebhookEvent, type GlobalWebhookResponse, HTTPError, HTTPNotFoundError, type HTTPStatusCode, type InfoStatusCode, type Input, type InputField, type InputFields, type Invoke, type LogEntry, type LogLevel, type Logger, type ManualTrigger, type MessageField, NonRetryableError, type NoneAuthentication, NotFoundError, type OAuth2Authentication, type ObjectInputField, type PaginatedResponse, type PollingTrigger, RateLimitHitError, type RedirectStatusCode, type RefInputField, type RequestClient, type RequestMiddleware, type SchemaInputField, type ServerErrorStatusCode, StaleAuthenticationError, type StatusCode, type StepperApp, type SubscriptionOptionFilter, type SubscriptionOptions, type SuccessStatusCode, type TemporaryFile, type Trigger, UnauthorizedError, UnknownError, type UnofficialStatusCode, UnprocessableEntityError, type WebhookBaseTrigger, type WebhookPayload, type WebhookPollSourceTrigger, type WebhookSourceTrigger, type WebhookTrigger, action, app, authentication, trigger };

package/package.json

@@ -1,15 +1,12 @@
 {
   "name": "@stepper-io/core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Core types and runtime helpers for building Stepper apps",
-  "main": "dist/index.mjs",
-  "types": "dist/index.d.mts",
+  "main": "./dist/index.mjs",
   "exports": {
     ".": {
-      "source": "./src/index.ts",
       "types": "./dist/index.d.mts",
-      "import": "./dist/index.mjs",
-      "default": "./dist/index.mjs"
+      "import": "./dist/index.mjs"
     }
   },
   "files": [
@@ -45,5 +42,6 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit"
-  }
+  },
+  "types": "./dist/index.d.mts"
 }