@cliptude/cli 0.1.12 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -71,6 +71,24 @@ footage under every beat, the transition on each cut, two-image reveals, and fre
71
71
  lists the graphics, `transitions`, `reveal_styles` and `sounds` (with previews). The plan schema and rules are in
72
72
  `skills/cliptude-plan/SKILL.md`. The job costs the same as the website price.
73
73
 
74
+ ### Product videos from a store
75
+
76
+ Turn a store product into a 6 to 60 minute educational YouTube video: about 80% teaching, then the product, with its
77
+ real photos composited into the closing boards (never regenerated). Any Shopify product URL works with no setup; other
78
+ stores work through the page's structured data; a store connected at cliptude.com/integrations/stores/ (or that
79
+ installed the Cliptude Shopify app) can also be searched.
80
+
81
+ ```
82
+ cliptude product fetch https://store.com/products/handle # product_id + 3 angles
83
+ cliptude product script <product-id> --angle 1 --duration 10-12 --discount-code YOUTUBE15
84
+ cliptude product status <job-id> # until script_ready; review the script
85
+ cliptude product render <job-id> --aspect-ratio 16:9 # returns at once
86
+ cliptude product status <job-id> # until ready_for_review; open editor_url
87
+ ```
88
+
89
+ MCP tools: `fetch_product_context`, `draft_product_script`, `render_product_video`, `get_product_video_status`.
90
+ None of them waits for a render; poll the status tool.
91
+
74
92
  `--title` is required. Provide **one** of `--prompt`, `--script` / `--script-file`, `--voiceover`, or `--talking-head`. Never copy the title into `--prompt`. If you only have a topic, follow **cliptude-script** (web search → spoken narration → `--script-file`), or ask Cliptude to write it with `cliptude script`. After a completed `script` or `voiceover` job, `cliptude continue <job-id>` turns that same job into a full video (reuses the script; voiceover jobs reuse the TTS file). `--voiceover` is a local audio file (same as create.html); it is transcribed and skips TTS — do not combine it with prompt/script. `--talking-head` is a presenter video on a Talking Head template (MP4, MOV, WEBM, AVI); it is transcribed and skips TTS. Optional `--duration` is a wizard bucket (`3-4`, `6-8`, `10-12`, …). Omit it to use the template duration, or the word-count estimate when you pass `--script`. Uploaded audio or talking-head video sets duration from the file. Avatar Video templates can override **Avatar Intro Only** and **AI Image + AI Video** with `--avatar-intro-only` / `--no-avatar-intro-only` and `--avatar-ai-footage` / `--no-avatar-ai-footage`. Omit those flags to keep the template. `generate` / `script` / `voiceover` / `continue` return immediately (`queued`). Poll `status`.
75
93
 
76
94
  ## MCP
@@ -143,6 +143,15 @@ def _run_auth(auth_cmd: str) -> None:
143
143
  print(f"Logged in{f' as {email}' if email else '.'}")
144
144
 
145
145
 
146
+ def _review_arg(value: str) -> dict:
147
+ """--review "quote|author|rating" -> {quote, author, rating}."""
148
+ parts = [p.strip() for p in value.split("|")]
149
+ review = {"quote": parts[0], "author": parts[1] if len(parts) > 1 else ""}
150
+ if len(parts) > 2 and parts[2]:
151
+ review["rating"] = float(parts[2])
152
+ return review
153
+
154
+
146
155
  def main(argv: list[str] | None = None) -> None:
147
156
  parser = argparse.ArgumentParser(
148
157
  prog="cliptude",
@@ -395,6 +404,38 @@ def main(argv: list[str] | None = None) -> None:
395
404
  )
396
405
  cont.add_argument("job_id")
397
406
 
407
+ prod = sub.add_parser(
408
+ "product",
409
+ help="Product videos from a store: fetch a product, draft its 80/20 script, render, check status",
410
+ formatter_class=argparse.RawDescriptionHelpFormatter,
411
+ epilog=(
412
+ "examples:\n"
413
+ " cliptude product fetch https://store.com/products/handle\n"
414
+ " cliptude product script <product-id> --angle 1 --duration 10-12 --discount-code YOUTUBE15\n"
415
+ " cliptude product render <job-id> --aspect-ratio 16:9\n"
416
+ " cliptude product status <job-id>"
417
+ ),
418
+ )
419
+ prod_sub = prod.add_subparsers(dest="product_cmd", required=True)
420
+ pf = prod_sub.add_parser("fetch", help="Read a product URL (or search a store) and get 3 video angles")
421
+ pf.add_argument("url_or_query")
422
+ pf.add_argument("--store", default="", help="Store domain to search, e.g. acme.com")
423
+ ps = prod_sub.add_parser("script", help="Queue the 80/20 educational script for a product")
424
+ ps.add_argument("product_id")
425
+ ps.add_argument("--angle", default="0", help="Angle index 0-2, or a custom educational title")
426
+ ps.add_argument("--duration", default="6-8", help="6-8, 10-12, 18-20, 30-40, 50-60 or minutes (6-60)")
427
+ ps.add_argument("--template", default="", help="Faceless Documentary template id")
428
+ ps.add_argument("--title", default="")
429
+ ps.add_argument("--discount-code", default="")
430
+ ps.add_argument("--cta-url", default="")
431
+ ps.add_argument("--review", action="append", default=[],
432
+ help='A real customer review, "quote|author|rating" (repeat up to 3 times)')
433
+ pr = prod_sub.add_parser("render", help="Produce the video from a ready product script")
434
+ pr.add_argument("job_id")
435
+ pr.add_argument("--aspect-ratio", default="16:9")
436
+ pst = prod_sub.add_parser("status", help="Stage, script, preview link and MP4 of a product video")
437
+ pst.add_argument("job_id")
438
+
398
439
  pj = sub.add_parser(
399
440
  "plan-job",
400
441
  help="Start an agent-planned job: Cliptude voices the narration and stops at plan_ready",
@@ -682,6 +723,20 @@ def main(argv: list[str] | None = None) -> None:
682
723
  _print({"ok": True, "path": str(dest.resolve())})
683
724
  elif args.cmd == "continue":
684
725
  _print(client.continue_job(args.job_id))
726
+ elif args.cmd == "product":
727
+ if args.product_cmd == "fetch":
728
+ _print(client.fetch_product_context(args.url_or_query, store_domain=args.store or None))
729
+ elif args.product_cmd == "script":
730
+ angle = int(args.angle) if str(args.angle).isdigit() else args.angle
731
+ _print(client.draft_product_script(
732
+ args.product_id, angle=angle, duration=args.duration, template_id=args.template or None,
733
+ title=args.title or None, discount_code=args.discount_code or None, cta_url=args.cta_url or None,
734
+ reviews=[_review_arg(r) for r in args.review] or None,
735
+ ))
736
+ elif args.product_cmd == "render":
737
+ _print(client.render_product_video(args.job_id, aspect_ratio=args.aspect_ratio))
738
+ else:
739
+ _print(client.get_product_video_status(args.job_id))
685
740
  elif args.cmd == "editor":
686
741
  _print(client.open_editor_project(args.job_id))
687
742
  elif args.cmd == "agent":
@@ -651,6 +651,47 @@ class CliptudeClient:
651
651
  """Queue a completed script/voiceover job, or a plan job with a locked plan, as a full video."""
652
652
  return self.request("POST", f"/api/v1/jobs/{job_id}/continue")
653
653
 
654
+ # Product videos (store products: Shopify, any store page) --------------------------------------
655
+
656
+ def fetch_product_context(self, product_url_or_query: str, *, store_domain: str | None = None) -> Any:
657
+ """Read a store product (URL, connected-store id/handle, or a search on store_domain) and get 3 angles."""
658
+ body: dict[str, Any] = {"url_or_query": product_url_or_query}
659
+ if store_domain:
660
+ body["store_domain"] = store_domain
661
+ return self.request("POST", "/api/v1/commerce/products/fetch", json_body=body)
662
+
663
+ def draft_product_script(
664
+ self,
665
+ product_id: str,
666
+ *,
667
+ angle: Any = None,
668
+ duration: str | int | None = None,
669
+ template_id: str | None = None,
670
+ title: str | None = None,
671
+ discount_code: str | None = None,
672
+ cta_url: str | None = None,
673
+ cta_text: str | None = None,
674
+ image_urls: list[str] | None = None,
675
+ reviews: list[dict] | None = None,
676
+ ) -> Any:
677
+ """Queue the 80/20 educational script for a product; returns {script_id, ...} immediately."""
678
+ body: dict[str, Any] = {"product_id": product_id}
679
+ for key, value in (
680
+ ("angle", angle), ("duration", duration), ("template_id", template_id), ("title", title),
681
+ ("discount_code", discount_code), ("cta_url", cta_url), ("cta_text", cta_text),
682
+ ("image_urls", image_urls), ("reviews", reviews),
683
+ ):
684
+ if value not in (None, "", []):
685
+ body[key] = value
686
+ return self.request("POST", "/api/v1/commerce/scripts", json_body=body)
687
+
688
+ def render_product_video(self, job_id: str, *, aspect_ratio: str = "16:9") -> Any:
689
+ """Turn a ready product script into the video on the same job id (returns immediately)."""
690
+ return self.request("POST", f"/api/v1/commerce/videos/{job_id}/render", json_body={"aspect_ratio": aspect_ratio})
691
+
692
+ def get_product_video_status(self, job_id: str) -> Any:
693
+ return self.request("GET", f"/api/v1/commerce/videos/{job_id}")
694
+
654
695
  # Agent-planned videos -------------------------------------------------------------------------
655
696
 
656
697
  def upload_plan_media(self, job_id: str, path: str | Path) -> Any:
@@ -126,7 +126,13 @@ def build_server(*, with_http_auth: bool = False):
126
126
  "and Cliptude only voices, sources and renders. create_plan_job, poll get_job until "
127
127
  "plan_ready, get_narration (numbered sentences), get_kind_catalog (compact first), write the "
128
128
  "plan, check_plan until valid, lock_plan, continue_job, then get_plan_report. See the "
129
- "cliptude-plan skill."
129
+ "cliptude-plan skill. "
130
+ "PRODUCT VIDEOS (Shopify product URLs, a connected store, or any store's product page): "
131
+ "fetch_product_context, show the user the 3 angles, draft_product_script with their pick and a "
132
+ "duration (6-8 to 50-60 minutes), poll get_product_video_status until script_ready, let the user "
133
+ "review the script, render_product_video, poll until ready_for_review, give the user editor_url, "
134
+ "and only after they approve render with open_editor_project + render_project + get_render. "
135
+ "Never publish anything to a store or YouTube without the user's explicit go-ahead."
130
136
  ),
131
137
  }
132
138
  if with_http_auth:
@@ -571,6 +577,87 @@ def build_server(*, with_http_auth: bool = False):
571
577
  except Exception as exc:
572
578
  return _err(exc)
573
579
 
580
+ @mcp.tool(
581
+ title="Fetch product context",
582
+ annotations=ToolAnnotations(title="Fetch product context", read_only_hint=True, destructive_hint=False,
583
+ open_world_hint=True),
584
+ )
585
+ def fetch_product_context(
586
+ product_url_or_query: Annotated[str, Field(min_length=1, description=(
587
+ "A product page URL (any Shopify store, e.g. https://store.com/products/handle; other stores "
588
+ "such as WooCommerce or Etsy work through the page's structured data), a connected store's "
589
+ "product id/handle, or a search term together with store_domain."))],
590
+ store_domain: Annotated[str | None, Field(description=(
591
+ "Store to search or read from, e.g. acme.com or acme.myshopify.com. Uses the user's connected "
592
+ "store when it matches."))] = None,
593
+ ) -> dict[str, Any]:
594
+ """Read a store product: title, price, variants, description and its real image URLs, saved as product_id, plus 3 educational YouTube video angles (80% teaching, 20% product). A search that matches several products returns candidates; fetch again with the chosen URL. Show the user the angles before drafting."""
595
+ try:
596
+ return _client().fetch_product_context(product_url_or_query, store_domain=store_domain)
597
+ except Exception as exc:
598
+ return _err(exc)
599
+
600
+ @mcp.tool(
601
+ title="Draft product video script",
602
+ annotations=ToolAnnotations(title="Draft product video script", read_only_hint=False, destructive_hint=False),
603
+ )
604
+ def draft_product_script(
605
+ product_id: Annotated[str, Field(min_length=8, description="product_id from fetch_product_context")],
606
+ angle: Annotated[int | str | dict | None, Field(description=(
607
+ "Index (0-2) of an angle from fetch_product_context, an angle object {title, problem, hook}, or "
608
+ "a custom educational title. Default 0."))] = None,
609
+ duration: Annotated[str | int | None, Field(description=(
610
+ "Length: 6-8, 10-12, 18-20, 30-40 or 50-60 (minutes), or a number of minutes from 6 to 60. "
611
+ "Default 6-8."))] = None,
612
+ template_id: Annotated[str | None, Field(description=(
613
+ "Faceless Documentary template to use (voice, look, music). Omit to use the latest one, or a "
614
+ "default Product Explainer template."))] = None,
615
+ title: Annotated[str | None, Field(description="Video title. Defaults to the angle title.")] = None,
616
+ discount_code: Annotated[str | None, Field(description="Discount code the merchant gave. Never invent one.")] = None,
617
+ cta_url: Annotated[str | None, Field(description="Where viewers should go. Defaults to the product page.")] = None,
618
+ image_urls: Annotated[list[str] | None, Field(description=(
619
+ "Which of the product's image URLs to show (defaults to all of them)."))] = None,
620
+ reviews: Annotated[list[dict] | None, Field(description=(
621
+ "Up to 3 real customer reviews the merchant gave you, word for word: "
622
+ "[{quote, author, rating (1-5), verified}]. Enables the review card. Never write or "
623
+ "paraphrase a review."))] = None,
624
+ ) -> dict[str, Any]:
625
+ """Queue the narration for a product video: an educational documentary for about 80% of its length, then a natural bridge to the product (real specs, price, offer) in the last 20%. Returns script_id (the job id) immediately; poll get_product_video_status until stage is script_ready, then show the user the script."""
626
+ try:
627
+ return _client().draft_product_script(
628
+ product_id, angle=angle, duration=duration, template_id=template_id, title=title,
629
+ discount_code=discount_code, cta_url=cta_url, image_urls=image_urls, reviews=reviews,
630
+ )
631
+ except Exception as exc:
632
+ return _err(exc)
633
+
634
+ @mcp.tool(
635
+ title="Render product video",
636
+ annotations=ToolAnnotations(title="Render product video", read_only_hint=False, destructive_hint=False),
637
+ )
638
+ def render_product_video(
639
+ script_id: Annotated[str, Field(min_length=8, description="script_id / job_id from draft_product_script, once script_ready")],
640
+ aspect_ratio: Annotated[str, Field(description="16:9 (YouTube), 9:16, 1:1 or 4:5")] = "16:9",
641
+ ) -> dict[str, Any]:
642
+ """Produce the video from the approved script on the same job id: voiceover, sourcing, motion graphics, and the merchant's real product photos composited into the closing product boards. Returns {job_id, status, editor_url, estimated_minutes} immediately; never wait in this call. Poll get_product_video_status."""
643
+ try:
644
+ return _client().render_product_video(script_id, aspect_ratio=aspect_ratio)
645
+ except Exception as exc:
646
+ return _err(exc)
647
+
648
+ @mcp.tool(
649
+ title="Get product video status",
650
+ annotations=ToolAnnotations(title="Get product video status", read_only_hint=True, destructive_hint=False),
651
+ )
652
+ def get_product_video_status(
653
+ job_id: Annotated[str, Field(min_length=8, description="Job id from draft_product_script / render_product_video")],
654
+ ) -> dict[str, Any]:
655
+ """Stage of a product video (script_drafting, script_ready, producing, ready_for_review, rendered, failed) with the script once written, the editor_url to preview, the MP4 URL once rendered, and next_step telling you what to do."""
656
+ try:
657
+ return _client().get_product_video_status(job_id)
658
+ except Exception as exc:
659
+ return _err(exc)
660
+
574
661
  @mcp.tool(
575
662
  title="Create agent-planned job",
576
663
  annotations=ToolAnnotations(title="Create agent-planned job", read_only_hint=False, destructive_hint=False),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cliptude/cli",
3
- "version": "0.1.12",
3
+ "version": "0.1.13",
4
4
  "description": "Cliptude CLI — generate videos from saved templates.",
5
5
  "homepage": "https://github.com/cliptude/cliptude#readme",
6
6
  "bin": {
package/pyproject.toml CHANGED
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "cliptude-mcp"
7
- version = "0.1.12"
7
+ version = "0.1.13"
8
8
  description = "Cliptude jobs CLI and MCP server (thin client of /api/v1)."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"