aemdm 0.4.1 → 0.5.0

package/dist/cli.js

@@ -39,6 +39,7 @@ const assetGetSchema = z
     output: z.string().optional(),
     metadata: z.boolean().default(false),
     imsToken: z.string().optional(),
+    mimeType: z.string().optional(),
 })
     .superRefine((value, ctx) => {
     if (value.metadata && value.output) {
@@ -193,6 +194,22 @@ async function handleAssetGet(assetId, options, runtime) {
         writeJson(runtime.stdout, metadata);
         return;
     }
+    let mimeType = parsed.mimeType;
+    if (!parsed.original && !parsed.format && !parsed.binary && !mimeType) {
+        if (imsToken) {
+            const metadata = await requestJson(buildMetadataUrl(baseUrl, assetId), {
+                imsToken,
+                fetchImpl: runtime.fetchImpl,
+            });
+            mimeType = metadata?.repositoryMetadata?.["dc:format"];
+            if (mimeType)
+                verbose(runtime, `detected mime type: ${mimeType}`);
+        }
+        else {
+            throw new CliError("Cannot determine asset type without authentication. " +
+                "Provide --format for images, --original for documents, or --ims-token to auto-detect.");
+        }
+    }
     const url = buildAssetUrl(baseUrl, {
         assetId,
         seoName: parsed.seoName,
@@ -202,6 +219,7 @@ async function handleAssetGet(assetId, options, runtime) {
         quality: parsed.quality,
         maxQuality: parsed.maxQuality,
         original: parsed.original,
+        mimeType,
     });
     if (!parsed.binary) {
         writeLine(runtime.stdout, url);
@@ -285,6 +303,7 @@ async function handleSearch(options, runtime) {
             return;
         }
         const dimensions = resolveDimensions(parsed.size, parsed.width, parsed.height);
+        const mimeType = firstHit.repositoryMetadata?.["dc:format"];
         const assetUrl = buildAssetUrl(baseUrl, {
             assetId,
             seoName: parsed.seoName,
@@ -294,6 +313,7 @@ async function handleSearch(options, runtime) {
             quality: parsed.quality,
             maxQuality: parsed.maxQuality,
             original: parsed.original,
+            mimeType,
         });
         if (parsed.firstUrl) {
             writeLine(runtime.stdout, assetUrl);
@@ -353,6 +373,33 @@ function buildProgram(runtime) {
         .version(pkg.version)
         .showHelpAfterError()
         .option("-v, --verbose", "Show additional diagnostic output")
+        .addHelpText("after", `
+Bucket:
+  Most commands need a delivery bucket. Provide it in one of three ways:
+    1. --bucket delivery-p123-e456.adobeaemcloud.com  (per-command flag)
+    2. AEMDM_BUCKET environment variable
+    3. Save a default:  aemdm --bucket delivery-p123-e456.adobeaemcloud.com
+       This writes to ~/.aemdm/config.json and is used when no flag or env var is set.
+
+Authentication:
+  Public asset URLs and basic metadata (HEAD-based) require no authentication.
+  Full metadata, binary downloads, and search require an IMS bearer token:
+    1. --ims-token <token>  (per-command flag)
+    2. AEMDM_IMS_TOKEN environment variable
+    3. Save a default:  aemdm --ims-token <token>
+       This writes the token to ~/.aemdm/config.json for reuse.
+
+  Search also requires an Adobe API key:
+    1. --api-key <key>  (per-command flag)
+    2. AEMDM_API_KEY environment variable
+
+Examples:
+  aemdm --bucket delivery-p123-e456.adobeaemcloud.com   Save default bucket
+  aemdm asset get urn:aaid:aem:1234                      Print delivery URL
+  aemdm asset get urn:aaid:aem:1234 --format webp        Print URL with format
+  aemdm asset get urn:aaid:aem:1234 --metadata            Fetch asset metadata
+  aemdm search --text "hero banner"                      Search by text
+  aemdm search --text "logo" --first-url --format png    Search and get URL`)
         .configureOutput({
         writeOut: (text) => runtime.stdout.write(text),
         writeErr: (text) => runtime.stderr.write(text),
@@ -369,7 +416,8 @@ function buildProgram(runtime) {
         .option("--output <file>", "Output file path for --binary. Use - for stdout")
         .option("--metadata", "Fetch metadata JSON instead of building a URL")
         .option("--ims-token <token>", "IMS bearer token for metadata or binary requests")
-        .action((assetId, options) => handleAssetGet(assetId, options, runtime));
+        .option("--mime-type <type>", "Asset MIME type (skips metadata lookup for route detection)")
+        .action((assetId, options, cmd) => handleAssetGet(assetId, { ...cmd.parent.opts(), ...options }, runtime));
     configureCommonDeliveryOptions(program.command("search").description("Search assets and optionally resolve the first result"))
         .option("--bucket <bucket-or-url>", "Bucket host or full bucket URL")
         .option("--ims-token <token>", "IMS bearer token")
@@ -401,12 +449,39 @@ Core commands:
 - aemdm asset get <assetId>
 - aemdm search
 
+Bucket configuration (pick one):
+- --bucket delivery-p123-e456.adobeaemcloud.com  (per-command flag)
+- AEMDM_BUCKET environment variable
+- Save a default: aemdm --bucket delivery-p123-e456.adobeaemcloud.com
+  This writes to ~/.aemdm/config.json and is used when no flag or env var is set.
+
+Authentication:
+- Public asset URLs and basic metadata (HEAD-based) require no authentication.
+- Full metadata, binary downloads, and search require an IMS bearer token (pick one):
+  1. --ims-token <token>  (per-command flag)
+  2. AEMDM_IMS_TOKEN environment variable
+  3. Save a default: aemdm --ims-token <token>
+     This writes the token to ~/.aemdm/config.json for reuse.
+- Both bucket and token can be saved together: aemdm --bucket <host> --ims-token <token>
+- Search also requires an Adobe API key via --api-key <key> or AEMDM_API_KEY.
+
+URL format:
+- Images: https://<bucket>/adobe/assets/<assetId>/as/<seoName>.<format>
+- Documents/video: https://<bucket>/adobe/assets/<assetId>/original/as/<seoName>
+- Default seo-name is "asset", default format is "png".
+- Use --format to override (gif, png, jpg, jpeg, webp, avif).
+- Use --seo-name to set a custom SEO-friendly name segment.
+
+Route detection:
+- When authenticated, asset get auto-detects the MIME type via the metadata endpoint.
+  Images get the /as/<seoName>.<format> route; documents/video get /original/as/<seoName>.
+- When unauthenticated, you must specify --format (for images) or --original (for documents).
+- Use --mime-type <type> to skip the metadata lookup when you already know the type
+  (e.g. from a prior search result's dc:format field).
+- search --first-url auto-detects using the dc:format from the search hit (no extra call).
+
 Important defaults:
-- Bucket comes from --bucket or AEMDM_BUCKET.
-- A standalone call like aemdm --bucket delivery-p123-e456.adobeaemcloud.com saves the default bucket to the local aemdm profile config.
-- aemdm --ims-token <token> saves the IMS token to the profile config. Both can be saved together.
-- Search auth comes from --ims-token/AEMDM_IMS_TOKEN/profile config and --api-key/AEMDM_API_KEY.
-- asset get prints a URL by default.
+- asset get prints a delivery URL by default.
 - asset get --metadata prints full JSON metadata when authenticated, or basic public JSON metadata when no token is supplied.
 - asset get --binary downloads the asset and requires --output.
 - search --first-id prints one asset ID for piping.
@@ -419,6 +494,7 @@ Asset URL examples:
 - aemdm asset get urn:aaid:aem:1234 --original --binary --output ./asset.bin
 - aemdm asset get urn:aaid:aem:1234 --metadata
 - aemdm asset get urn:aaid:aem:1234 --metadata --ims-token <token>
+- aemdm asset get urn:aaid:aem:1234 --mime-type application/pdf
 
 Search examples:
 - aemdm search --text "hero banner"
@@ -444,8 +520,12 @@ LLM usage guidance:
 - Use search when you need to discover an asset by metadata or text.
 - Prefer --first-id or --ids-only when another CLI call needs asset IDs.
 - Prefer --first-url when the user wants a delivery URL from a search result.
+  --first-url uses the dc:format from the search hit to pick the correct route automatically.
 - Prefer --first-metadata when the user wants the resolved asset metadata after search.
 - Prefer --first-binary with --output when the user wants the downloaded file.
+- When piping search results to asset get, pass --mime-type with the dc:format from the
+  search result to avoid an extra metadata call and ensure the correct route.
+  Example: aemdm asset get <id> --mime-type application/pdf
 `;
 }
 function parseStandaloneConfig(argv) {

package/dist/lib/delivery.js

@@ -5,6 +5,9 @@ export const TRANSFORM_FALLBACK_FORMAT = "png";
 export const deliveryFormatSchema = z.enum(["gif", "png", "jpg", "jpeg", "webp", "avif"]);
 const qualitySchema = z.number().int().min(1).max(100);
 const dimensionSchema = z.number().int().min(1);
+function isImageMimeType(mimeType) {
+    return mimeType.startsWith("image/");
+}
 export function parseSize(value) {
     const match = /^(?<width>\d+)?x(?<height>\d+)?$/i.exec(value.trim());
     if (!match?.groups) {
@@ -58,7 +61,9 @@ export function buildAssetUrl(baseUrl, options) {
     if (options.height !== undefined) {
         dimensionSchema.parse(options.height);
     }
-    if (options.original) {
+    const useOriginal = options.original ||
+        (options.mimeType !== undefined && !isImageMimeType(options.mimeType));
+    if (useOriginal) {
         return `${normalizedBase}/${encodedAssetId}/original/as/${encodedSeoName}`;
     }
     const shouldUseTransformRoute = options.format !== undefined ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aemdm",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "CLI for Adobe Dynamic Media with OpenAPI",
   "license": "Apache-2.0",
   "author": "Chris Pilsworth",
@@ -41,7 +41,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "aemdm": "^0.4.0",
+    "aemdm": "^0.4.1",
     "commander": "^14.0.1",
     "zod": "^4.1.12"
   },