@zapier/policy-context 0.9.0 → 1.0.0

package/dist/index.d.ts

@@ -1,12 +1,8 @@
-import { z } from 'zod';
 import * as _zapier_policy_schema from '@zapier/policy-schema';
-import { JsonValue, Condition, Policy } from '@zapier/policy-schema';
+import { Condition, Policy } from '@zapier/policy-schema';
+export { JsonValueSchema } from '@zapier/policy-schema';
+import { z } from 'zod';
 
-/**
- * Zod schema for arbitrary JSON values. Used across context schemas for
- * unstructured fields like `body_json` and `inputs`.
- */
-declare const JsonValueSchema: z.ZodCustom<JsonValue, JsonValue>;
 /**
  * Parsed URL components for policy evaluation.
  * Matches the ParsedUrl shape from @zapier/policy-schema so that
@@ -42,7 +38,7 @@ declare function buildUrlString(parsed: ParsedUrl): string;
  */
 declare const HttpRequestContextSchema: z.ZodObject<{
     request_type: z.ZodLiteral<"http_request">;
-    method: z.ZodString;
+    method: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
     url: z.ZodObject<{
         scheme: z.ZodString;
         host: z.ZodString;
@@ -52,32 +48,90 @@ declare const HttpRequestContextSchema: z.ZodObject<{
     }, z.core.$strip>;
     headers: z.ZodRecord<z.ZodString, z.ZodString>;
     body: z.ZodNullable<z.ZodString>;
-    body_json: z.ZodNullable<z.ZodCustom<JsonValue, JsonValue>>;
+    body_json: z.ZodNullable<z.ZodType<_zapier_policy_schema.JsonValue, unknown, z.core.$ZodTypeInternals<_zapier_policy_schema.JsonValue, unknown>>>;
     connection_id: z.ZodOptional<z.ZodString>;
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type HttpRequestContext = z.infer<typeof HttpRequestContextSchema>;
 /**
- * Action run context for approval/policy flows.
- * Sent by sdkapi when an action run is denied, stored by approvalsapi,
- * and used to build policy conditions.
+ * Canonical Zapier action types.
+ *
+ * Mirrors the `action_type` enum in sdkapi's OpenAPI spec
+ * (`packages/openapi-spec/openapi.d.ts` `action_type`). Single source of
+ * truth for any code that branches on or filters by action_type — keeps
+ * `ActionRunContextSchema`, `BuildActionRunContextOptionsSchema`, and the
+ * `READ_ACTION_TYPES` allowlist in `connection-policy.ts` aligned.
  */
-declare const ActionRunContextSchema: z.ZodObject<{
+declare const ActionTypeSchema: z.ZodEnum<{
+    filter: "filter";
+    read: "read";
+    read_bulk: "read_bulk";
+    run: "run";
+    search: "search";
+    search_and_write: "search_and_write";
+    search_or_write: "search_or_write";
+    write: "write";
+}>;
+type ActionType = z.infer<typeof ActionTypeSchema>;
+/**
+ * Parse an action resource string of the form
+ * `action/{selected_api}/{action_type}/{action_key}` into its parts.
+ * Throws if the string doesn't match the canonical 4-segment shape or
+ * if its `action_type` segment isn't one of the canonical 8 — every
+ * action_run context that has been through `ActionRunContextSchema` is
+ * guaranteed to parse cleanly, so a thrown error here means upstream
+ * validation was bypassed.
+ */
+declare function parseActionResource(resource: string): {
+    selected_api: string;
+    action_type: ActionType;
+    action_key: string;
+};
+declare const ActionRunContextSchema: z.ZodPipe<z.ZodObject<{
     request_type: z.ZodLiteral<"action_run">;
-    selected_api: z.ZodString;
-    action_type: z.ZodString;
-    action_key: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+    selected_api: z.ZodOptional<z.ZodString>;
+    action_type: z.ZodOptional<z.ZodEnum<{
+        filter: "filter";
+        read: "read";
+        read_bulk: "read_bulk";
+        run: "run";
+        search: "search";
+        search_and_write: "search_and_write";
+        search_or_write: "search_or_write";
+        write: "write";
+    }>>;
+    action_key: z.ZodOptional<z.ZodString>;
     connection_id: z.ZodOptional<z.ZodString>;
-    inputs: z.ZodOptional<z.ZodCustom<JsonValue, JsonValue>>;
+    inputs: z.ZodOptional<z.ZodType<_zapier_policy_schema.JsonValue, unknown, z.core.$ZodTypeInternals<_zapier_policy_schema.JsonValue, unknown>>>;
     reason: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+    reason?: string | undefined;
+    inputs?: _zapier_policy_schema.JsonValue | undefined;
+    connection_id?: string | undefined;
+    request_type: "action_run";
+    resource: string;
+}, {
+    request_type: "action_run";
+    resource?: string | undefined;
+    selected_api?: string | undefined;
+    action_type?: "filter" | "read" | "read_bulk" | "run" | "search" | "search_and_write" | "search_or_write" | "write" | undefined;
+    action_key?: string | undefined;
+    connection_id?: string | undefined;
+    inputs?: _zapier_policy_schema.JsonValue | undefined;
+    reason?: string | undefined;
+}>>;
 type ActionRunContext = z.infer<typeof ActionRunContextSchema>;
 /**
- * Discriminated union of all request context types.
+ * Union of all request context types, keyed on `request_type`.
+ *
+ * Plain `z.union` (not `z.discriminatedUnion`) because
+ * `ActionRunContextSchema` carries a `.transform` and discriminated
+ * unions can't accept a `ZodEffects` member.
  */
-declare const RequestContextSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+declare const RequestContextSchema: z.ZodUnion<readonly [z.ZodObject<{
     request_type: z.ZodLiteral<"http_request">;
-    method: z.ZodString;
+    method: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
     url: z.ZodObject<{
         scheme: z.ZodString;
         host: z.ZodString;
@@ -87,18 +141,43 @@ declare const RequestContextSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>;
     headers: z.ZodRecord<z.ZodString, z.ZodString>;
     body: z.ZodNullable<z.ZodString>;
-    body_json: z.ZodNullable<z.ZodCustom<JsonValue, JsonValue>>;
+    body_json: z.ZodNullable<z.ZodType<_zapier_policy_schema.JsonValue, unknown, z.core.$ZodTypeInternals<_zapier_policy_schema.JsonValue, unknown>>>;
     connection_id: z.ZodOptional<z.ZodString>;
     reason: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
+}, z.core.$strip>, z.ZodPipe<z.ZodObject<{
     request_type: z.ZodLiteral<"action_run">;
-    selected_api: z.ZodString;
-    action_type: z.ZodString;
-    action_key: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+    selected_api: z.ZodOptional<z.ZodString>;
+    action_type: z.ZodOptional<z.ZodEnum<{
+        filter: "filter";
+        read: "read";
+        read_bulk: "read_bulk";
+        run: "run";
+        search: "search";
+        search_and_write: "search_and_write";
+        search_or_write: "search_or_write";
+        write: "write";
+    }>>;
+    action_key: z.ZodOptional<z.ZodString>;
     connection_id: z.ZodOptional<z.ZodString>;
-    inputs: z.ZodOptional<z.ZodCustom<JsonValue, JsonValue>>;
+    inputs: z.ZodOptional<z.ZodType<_zapier_policy_schema.JsonValue, unknown, z.core.$ZodTypeInternals<_zapier_policy_schema.JsonValue, unknown>>>;
     reason: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>], "request_type">;
+}, z.core.$strip>, z.ZodTransform<{
+    reason?: string | undefined;
+    inputs?: _zapier_policy_schema.JsonValue | undefined;
+    connection_id?: string | undefined;
+    request_type: "action_run";
+    resource: string;
+}, {
+    request_type: "action_run";
+    resource?: string | undefined;
+    selected_api?: string | undefined;
+    action_type?: "filter" | "read" | "read_bulk" | "run" | "search" | "search_and_write" | "search_or_write" | "write" | undefined;
+    action_key?: string | undefined;
+    connection_id?: string | undefined;
+    inputs?: _zapier_policy_schema.JsonValue | undefined;
+    reason?: string | undefined;
+}>>]>;
 type RequestContext = z.infer<typeof RequestContextSchema>;
 
 /**
@@ -115,7 +194,7 @@ declare const BuildHttpRequestContextOptionsSchema: z.ZodObject<{
     url: z.ZodString;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodUndefined]>>>;
     body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    body_json: z.ZodOptional<z.ZodCustom<_zapier_policy_schema.JsonValue, _zapier_policy_schema.JsonValue>>;
+    body_json: z.ZodOptional<z.ZodType<_zapier_policy_schema.JsonValue, unknown, z.core.$ZodTypeInternals<_zapier_policy_schema.JsonValue, unknown>>>;
     connection_id: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type BuildHttpRequestContextOptions = z.infer<typeof BuildHttpRequestContextOptionsSchema>;
@@ -137,14 +216,28 @@ type BuildHttpRequestContextOptions = z.infer<typeof BuildHttpRequestContextOpti
 declare function buildHttpRequestContext(options: BuildHttpRequestContextOptions): HttpRequestContext;
 declare const BuildActionRunContextOptionsSchema: z.ZodObject<{
     selected_api: z.ZodString;
-    action_type: z.ZodString;
+    action_type: z.ZodEnum<{
+        filter: "filter";
+        read: "read";
+        read_bulk: "read_bulk";
+        run: "run";
+        search: "search";
+        search_and_write: "search_and_write";
+        search_or_write: "search_or_write";
+        write: "write";
+    }>;
     action_key: z.ZodString;
     connection_id: z.ZodOptional<z.ZodString>;
-    inputs: z.ZodOptional<z.ZodCustom<_zapier_policy_schema.JsonValue, _zapier_policy_schema.JsonValue>>;
+    inputs: z.ZodOptional<z.ZodType<_zapier_policy_schema.JsonValue, unknown, z.core.$ZodTypeInternals<_zapier_policy_schema.JsonValue, unknown>>>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type BuildActionRunContextOptions = z.infer<typeof BuildActionRunContextOptionsSchema>;
 /**
  * Build a canonical ActionRunContext from raw action parts.
+ *
+ * Callers pass the three identity fields separately for readability;
+ * this validates them and collapses them into the canonical `resource`
+ * string the schema stores.
  */
 declare function buildActionRunContext(options: BuildActionRunContextOptions): ActionRunContext;
 
@@ -171,16 +264,27 @@ declare function buildDomainHttpConditions(context: HttpRequestContext): Conditi
  * @returns Condition[] for an action permission statement
  */
 declare function buildExactActionConditions(context: ActionRunContext): Condition[];
+/**
+ * The three identity fields that compose an action resource string.
+ */
+interface ActionResourceParts {
+    selected_api: string;
+    action_type: ActionType;
+    action_key: string;
+}
 /**
  * Build the resource string for an action.
  * Format: action/{selected_api}/{action_type}/{action_key}
  */
-declare function buildActionResource(context: ActionRunContext): string;
+declare function buildActionResource(parts: ActionResourceParts): string;
 /**
- * Build a broad action resource that matches all actions for an app.
- * Format: action/{selected_api}/{wildcard}/{wildcard}
+ * Build a broad action resource that matches all actions of the same type
+ * for an app (e.g. all reads, all writes). Scopes on `action_type` to
+ * avoid silently granting cross-type access.
+ *
+ * Format: action/{selected_api}/{action_type}/{wildcard}
  */
-declare function buildBroadActionResource(context: ActionRunContext): string;
+declare function buildBroadActionResource(parts: Pick<ActionResourceParts, "selected_api" | "action_type">): string;
 
 /**
  * Build an exact-match policy from any supported request context.
@@ -195,13 +299,35 @@ declare const AccessLevelSchema: z.ZodEnum<{
     read_write: "read_write";
 }>;
 type AccessLevel = z.infer<typeof AccessLevelSchema>;
+/** HTTP methods that count as side-effect-free reads for connection-level policies. */
+declare const READ_HTTP_METHODS: readonly ["GET", "HEAD", "OPTIONS"];
+/**
+ * Action types that count as side-effect-free reads for connection-level
+ * policies. `read_bulk` is the paginated/bulk variant of `read` — same
+ * external API semantics, no mutations. Widely used by major apps (Slack,
+ * Gmail, Jira, Salesforce, etc.) via the public `bulkReads` schema key.
+ * `filter` and `run` are excluded: neither has a runtime executor for
+ * external apps, and `filter` actions don't carry a connection_id anyway,
+ * so this allowlist has no effect on them.
+ */
+declare const READ_ACTION_TYPES: readonly ["read", "read_bulk", "search"];
+/**
+ * Returns true when the request needs write access (i.e. it is NOT a
+ * side-effect-free read). Mirrors the logic encoded in `buildConnectionPolicy`
+ * so UI surfaces that gate the read-vs-read_write choice stay consistent
+ * with the policies they generate.
+ */
+declare function isWriteRequest(context: RequestContext): boolean;
 /**
  * Build a connection-level policy that covers both HTTP and action access.
  *
  * Always produces three statements:
  * 1. `can_use` for the authentication
  * 2. `can_execute` on `http` scoped by connection_id (+ method filter for read)
- * 3. `can_execute` on `action/{selectedApi}/**` scoped by connection_id (+ action_type filter for read)
+ * 3. `can_execute` on `action/{selectedApi}/{action_type}/*` per allowed type,
+ *    scoped by connection_id. For read access, the resource list expands to
+ *    one entry per read action_type so the engine matches via the resource
+ *    string rather than a separate `path: ["action_type"]` condition.
  */
 declare function buildConnectionPolicy(options: {
     connectionId: string;
@@ -209,4 +335,4 @@ declare function buildConnectionPolicy(options: {
     accessLevel: AccessLevel;
 }): Policy;
 
-export { type AccessLevel, AccessLevelSchema, type ActionRunContext, ActionRunContextSchema, type BuildActionRunContextOptions, BuildActionRunContextOptionsSchema, type BuildHttpRequestContextOptions, BuildHttpRequestContextOptionsSchema, DEFAULT_PORTS, type HttpRequestContext, HttpRequestContextSchema, IGNORED_HEADERS, JsonValueSchema, type ParsedUrl, ParsedUrlSchema, type RequestContext, RequestContextSchema, buildActionResource, buildActionRunContext, buildBroadActionResource, buildConnectionPolicy, buildDomainHttpConditions, buildExactActionConditions, buildExactHttpConditions, buildHttpRequestContext, buildUrlString, parseUrl, toExactPolicy };
+export { type AccessLevel, AccessLevelSchema, type ActionRunContext, ActionRunContextSchema, type ActionType, ActionTypeSchema, type BuildActionRunContextOptions, BuildActionRunContextOptionsSchema, type BuildHttpRequestContextOptions, BuildHttpRequestContextOptionsSchema, DEFAULT_PORTS, type HttpRequestContext, HttpRequestContextSchema, IGNORED_HEADERS, type ParsedUrl, ParsedUrlSchema, READ_ACTION_TYPES, READ_HTTP_METHODS, type RequestContext, RequestContextSchema, buildActionResource, buildActionRunContext, buildBroadActionResource, buildConnectionPolicy, buildDomainHttpConditions, buildExactActionConditions, buildExactHttpConditions, buildHttpRequestContext, buildUrlString, isWriteRequest, parseActionResource, parseUrl, toExactPolicy };