📝 Add docstrings to jacob/feat-snippet-resource

alchemy/src/cloudflare/snippet-rule.ts

@@ -292,7 +292,14 @@ export const SnippetRule = Resource(
 );
 
 /**
- * Delete a snippet rule from a zone by its ID
+ * Removes a snippet rule identified by its ruleId from the specified zone.
+ *
+ * If the rule is the only snippet rule remaining, all snippet rules for the zone are deleted; otherwise the rule is removed and the remaining rules are updated.
+ *
+ * @param api - Cloudflare API client used to list and modify snippet rules
+ * @param zoneId - Zone identifier containing the snippet rule
+ * @param ruleId - Identifier of the snippet rule to remove
+ * @throws Errors encountered while listing, updating, or deleting rules are logged and rethrown
  * @internal
  */
 async function deleteSnippetRuleById(
@@ -343,8 +350,10 @@ async function deleteSnippetRuleById(
 }
 
 /**
- * List all snippet rules in a zone
+ * Retrieve the snippet rules configured for the given zone.
+ *
  * @internal
+ * @returns An array of `SnippetRuleResponse` objects representing the zone's snippet rules.
  */
 export async function listSnippetRules(
   api: CloudflareApi,
@@ -357,7 +366,11 @@ export async function listSnippetRules(
 }
 
 /**
- * Update snippet rules in a zone (replaces all rules)
+ * Replace all snippet rules for a Cloudflare zone with the provided set of rules.
+ *
+ * @param zoneId - The target zone identifier
+ * @param rules - Array of snippet rule inputs; each item should include `expression`, `snippetName`, optional `description`, and optional `enabled` (defaults to `true`)
+ * @returns The updated list of snippet rules as returned by the Cloudflare API
  * @internal
  */
 export async function updateSnippetRules(
@@ -381,7 +394,10 @@ export async function updateSnippetRules(
 }
 
 /**
- * Delete all snippet rules in a zone
+ * Remove all snippet rules for the given zone.
+ *
+ * Treats a missing resource (HTTP 404) as a successful no-op; throws an error for any other non-OK response.
+ *
  * @internal
  */
 export async function deleteSnippetRules(
@@ -393,4 +409,4 @@ export async function deleteSnippetRules(
   if (!response.ok && response.status !== 404) {
     throw new Error(`Failed to delete snippet rules: ${response.statusText}`);
   }
-}
+}

alchemy/src/cloudflare/snippet.ts

@@ -239,7 +239,11 @@ export const Snippet = Resource(
 );
 
 /**
- * Get script content from either inline script or file entrypoint
+ * Resolve and return the snippet's JavaScript source from inline `script` or a filesystem `entrypoint`.
+ *
+ * @param props - Snippet properties containing either an inline `script` or an `entrypoint` path
+ * @returns The snippet source code as a UTF-8 string
+ * @throws Error if neither `script` nor `entrypoint` is provided
  * @internal
  */
 async function getScriptContent(props: SnippetProps): Promise<string> {
@@ -264,8 +268,13 @@ interface SnippetResponse {
 }
 
 /**
- * Create or update a snippet
+ * Uploads a JavaScript snippet to a Cloudflare zone, creating or replacing the named snippet.
+ *
  * @internal
+ * @param zoneId - The Cloudflare zone identifier where the snippet will be stored
+ * @param snippetName - The unique name of the snippet within the zone
+ * @param content - The JavaScript source to upload as the snippet
+ * @throws If the Cloudflare API returns an error while creating or updating the snippet
  */
 export async function createOrUpdateSnippet(
   api: CloudflareApi,
@@ -302,8 +311,10 @@ export async function createOrUpdateSnippet(
 }
 
 /**
- * Check if a snippet exists
+ * Determine whether a Cloudflare snippet with the given name exists in the specified zone.
+ *
  * @internal
+ * @returns `true` if the snippet exists, `false` otherwise.
  */
 export async function snippetExists(
   api: CloudflareApi,
@@ -315,8 +326,13 @@ export async function snippetExists(
 }
 
 /**
- * Get a snippet by name
+ * Retrieve metadata for a Cloudflare snippet by name.
+ *
  * @internal
+ * @param api - Cloudflare API client used to perform the request
+ * @param zoneId - Identifier of the Cloudflare zone containing the snippet
+ * @param snippetName - The name of the snippet to retrieve
+ * @returns The snippet metadata (`SnippetResponse`)
  */
 export async function getSnippet(
   api: CloudflareApi,
@@ -330,8 +346,11 @@ export async function getSnippet(
 }
 
 /**
- * Get the content of a snippet
+ * Retrieve the raw content of a Cloudflare snippet.
+ *
  * @internal
+ * @returns The snippet's raw JavaScript content as a string.
+ * @throws When the Cloudflare API responds with an error for the snippet content request.
  */
 export async function getSnippetContent(
   api: CloudflareApi,
@@ -350,8 +369,10 @@ export async function getSnippetContent(
 }
 
 /**
- * List all snippets in a zone
+ * List all snippets for the given zone.
+ *
  * @internal
+ * @returns An array of snippet metadata objects for the zone.
  */
 export async function listSnippets(
   api: CloudflareApi,
@@ -364,8 +385,15 @@ export async function listSnippets(
 }
 
 /**
- * Delete a snippet from Cloudflare
+ * Remove a named snippet from a Cloudflare zone.
+ *
+ * Deletes the snippet identified by `snippetName` in the given `zoneId`. Treats a 404 response
+ * and the Cloudflare 400 message "requested snippet not found" as successful deletions; other
+ * non-OK responses are propagated via API error handling.
+ *
  * @internal
+ * @param zoneId - The Cloudflare zone identifier containing the snippet
+ * @param snippetName - The name of the snippet to delete
  */
 export async function deleteSnippet(
   api: CloudflareApi,
@@ -388,10 +416,10 @@ export async function deleteSnippet(
 }
 
 /**
- * Validates that a snippet name meets Cloudflare requirements due to strong restrictions on the name.
- * Cloudflare Snippets only allow lowercase letters (a-z), numbers (0-9), and underscores (_)
+ * Ensures a snippet name conforms to Cloudflare's naming rules.
  *
- * @throws Error if the name does not meet Cloudflare snippet requirements
+ * @returns `true` if the name is valid.
+ * @throws Error if the name is empty, longer than 255 characters, or contains characters other than lowercase letters (a-z), numbers (0-9), or underscores (_).
  * @internal
  */
 export function validateSnippetName(name: string): boolean {
@@ -410,4 +438,4 @@ export function validateSnippetName(name: string): boolean {
   }
 
   return true;
-}
+}