hap-cli 0.8.20__tar.gz → 0.8.22__tar.gz

{hap_cli-0.8.20 → hap_cli-0.8.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.20
+Version: 0.8.22
 Summary: CLI harness for Mingdao HAP - Enterprise no-code platform
 Author: hap-cli
 License: Apache-2.0
@@ -272,7 +272,7 @@ discover every subcommand.
 | `chat list` | Recent sessions |
 | `chat messages` | 1-on-1 / group / inbox messages |
 | `chat files` | Files shared in a chat |
-| `chat send-to-one` | Send a plain-text message to one or more users (1-on-1) |
+| `chat send-to-one` | Send a message, optionally with files (`--file`), to one or more users (1-on-1) |
 | `chat send-to-group` | Send a plain-text message to a group chat |
 | `chat card-detail` | Resolve embedded card references |
 
@@ -298,13 +298,21 @@ discover every subcommand.
 | `icon search` | Search icons by Chinese/English keyword (OR across terms, more matches rank higher); fewer than 10 matches get random suggestions appended; no keyword lists all |
 | `icon list [-n SIZE] [-p PAGE]` | List icons page by page with keywords (50 per page by default) |
 
+### attachment — stored files
+
+| Command | Description |
+|---|---|
+| `attachment share ADDRESS` | Create a link to a stored file that you can pass on (`--hours`, default 48) |
+
+> ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.
+
 ### upload — file upload
 
 | Command | Description |
 |---|---|
-| `upload [SOURCES...]` | Upload local paths or http(s) URLs to the file store; prints neutral uploaded-file descriptors (fileID/key/url/serverName/filePath/fileName/fileExt/originalFileName/fileSize) |
+| `upload [SOURCES...]` | Upload local paths or http(s) URLs to the file store; prints neutral uploaded-file descriptors (fileID/key/url/urlExpiresAt/serverName/filePath/fileName/fileExt/originalFileName/fileSize) |
 
-> A cross-feature capability — the same descriptors can be attached to a worksheet Attachment field, a chat message, a post, a calendar event, or a comment. Use `--files '[{"name":"cover.png","url":"https://..."}]'` to set display names; `--worksheet-id` / `--app-id` refine upload-token routing.
+> A cross-feature capability — the same descriptors can be attached to a worksheet Attachment field, a post, a calendar event, or a comment. The returned `url` is a temporary address for your own immediate use and stops working at `urlExpiresAt`; never send it to anyone. To share a file, attach it where it belongs — e.g. `hap chat send-to-one --file <path>`. Use `--files '[{"name":"cover.png","url":"https://..."}]'` to set display names; `--worksheet-id` / `--app-id` refine upload-token routing.
 
 ### config — local CLI settings
 
@@ -313,6 +321,7 @@ discover every subcommand.
 | `config show` | Display the current configuration summary |
 | `config completion [bash\|zsh\|fish] [--install]` | Enable `<Tab>` completion |
 | `config language [LANG]` | Switch UI language (`en` / `zh-Hans` / `zh-Hant` / `ja`) |
+| `config update [auto\|notify\|off]` | Self-upgrade mode; `notify` only reports, `off` never checks |
 | `config log on / off / status` | Toggle and inspect API logging |
 | `config log level LEVEL` | `DEBUG / INFO / WARNING / ERROR / CRITICAL` |
 | `config log view [--lines N] [--no-follow]` | Tail the log file |

{hap_cli-0.8.20/hap_cli → hap_cli-0.8.22}/README.md

@@ -243,7 +243,7 @@ discover every subcommand.
 | `chat list` | Recent sessions |
 | `chat messages` | 1-on-1 / group / inbox messages |
 | `chat files` | Files shared in a chat |
-| `chat send-to-one` | Send a plain-text message to one or more users (1-on-1) |
+| `chat send-to-one` | Send a message, optionally with files (`--file`), to one or more users (1-on-1) |
 | `chat send-to-group` | Send a plain-text message to a group chat |
 | `chat card-detail` | Resolve embedded card references |
 
@@ -269,13 +269,21 @@ discover every subcommand.
 | `icon search` | Search icons by Chinese/English keyword (OR across terms, more matches rank higher); fewer than 10 matches get random suggestions appended; no keyword lists all |
 | `icon list [-n SIZE] [-p PAGE]` | List icons page by page with keywords (50 per page by default) |
 
+### attachment — stored files
+
+| Command | Description |
+|---|---|
+| `attachment share ADDRESS` | Create a link to a stored file that you can pass on (`--hours`, default 48) |
+
+> ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.
+
 ### upload — file upload
 
 | Command | Description |
 |---|---|
-| `upload [SOURCES...]` | Upload local paths or http(s) URLs to the file store; prints neutral uploaded-file descriptors (fileID/key/url/serverName/filePath/fileName/fileExt/originalFileName/fileSize) |
+| `upload [SOURCES...]` | Upload local paths or http(s) URLs to the file store; prints neutral uploaded-file descriptors (fileID/key/url/urlExpiresAt/serverName/filePath/fileName/fileExt/originalFileName/fileSize) |
 
-> A cross-feature capability — the same descriptors can be attached to a worksheet Attachment field, a chat message, a post, a calendar event, or a comment. Use `--files '[{"name":"cover.png","url":"https://..."}]'` to set display names; `--worksheet-id` / `--app-id` refine upload-token routing.
+> A cross-feature capability — the same descriptors can be attached to a worksheet Attachment field, a post, a calendar event, or a comment. The returned `url` is a temporary address for your own immediate use and stops working at `urlExpiresAt`; never send it to anyone. To share a file, attach it where it belongs — e.g. `hap chat send-to-one --file <path>`. Use `--files '[{"name":"cover.png","url":"https://..."}]'` to set display names; `--worksheet-id` / `--app-id` refine upload-token routing.
 
 ### config — local CLI settings
 
@@ -284,6 +292,7 @@ discover every subcommand.
 | `config show` | Display the current configuration summary |
 | `config completion [bash\|zsh\|fish] [--install]` | Enable `<Tab>` completion |
 | `config language [LANG]` | Switch UI language (`en` / `zh-Hans` / `zh-Hant` / `ja`) |
+| `config update [auto\|notify\|off]` | Self-upgrade mode; `notify` only reports, `off` never checks |
 | `config log on / off / status` | Toggle and inspect API logging |
 | `config log level LEVEL` | `DEBUG / INFO / WARNING / ERROR / CRITICAL` |
 | `config log view [--lines N] [--no-follow]` | Tail the log file |

{hap_cli-0.8.20 → hap_cli-0.8.22/hap_cli}/README.md

@@ -243,7 +243,7 @@ discover every subcommand.
 | `chat list` | Recent sessions |
 | `chat messages` | 1-on-1 / group / inbox messages |
 | `chat files` | Files shared in a chat |
-| `chat send-to-one` | Send a plain-text message to one or more users (1-on-1) |
+| `chat send-to-one` | Send a message, optionally with files (`--file`), to one or more users (1-on-1) |
 | `chat send-to-group` | Send a plain-text message to a group chat |
 | `chat card-detail` | Resolve embedded card references |
 
@@ -269,13 +269,21 @@ discover every subcommand.
 | `icon search` | Search icons by Chinese/English keyword (OR across terms, more matches rank higher); fewer than 10 matches get random suggestions appended; no keyword lists all |
 | `icon list [-n SIZE] [-p PAGE]` | List icons page by page with keywords (50 per page by default) |
 
+### attachment — stored files
+
+| Command | Description |
+|---|---|
+| `attachment share ADDRESS` | Create a link to a stored file that you can pass on (`--hours`, default 48) |
+
+> ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.
+
 ### upload — file upload
 
 | Command | Description |
 |---|---|
-| `upload [SOURCES...]` | Upload local paths or http(s) URLs to the file store; prints neutral uploaded-file descriptors (fileID/key/url/serverName/filePath/fileName/fileExt/originalFileName/fileSize) |
+| `upload [SOURCES...]` | Upload local paths or http(s) URLs to the file store; prints neutral uploaded-file descriptors (fileID/key/url/urlExpiresAt/serverName/filePath/fileName/fileExt/originalFileName/fileSize) |
 
-> A cross-feature capability — the same descriptors can be attached to a worksheet Attachment field, a chat message, a post, a calendar event, or a comment. Use `--files '[{"name":"cover.png","url":"https://..."}]'` to set display names; `--worksheet-id` / `--app-id` refine upload-token routing.
+> A cross-feature capability — the same descriptors can be attached to a worksheet Attachment field, a post, a calendar event, or a comment. The returned `url` is a temporary address for your own immediate use and stops working at `urlExpiresAt`; never send it to anyone. To share a file, attach it where it belongs — e.g. `hap chat send-to-one --file <path>`. Use `--files '[{"name":"cover.png","url":"https://..."}]'` to set display names; `--worksheet-id` / `--app-id` refine upload-token routing.
 
 ### config — local CLI settings
 
@@ -284,6 +292,7 @@ discover every subcommand.
 | `config show` | Display the current configuration summary |
 | `config completion [bash\|zsh\|fish] [--install]` | Enable `<Tab>` completion |
 | `config language [LANG]` | Switch UI language (`en` / `zh-Hans` / `zh-Hant` / `ja`) |
+| `config update [auto\|notify\|off]` | Self-upgrade mode; `notify` only reports, `off` never checks |
 | `config log on / off / status` | Toggle and inspect API logging |
 | `config log level LEVEL` | `DEBUG / INFO / WARNING / ERROR / CRITICAL` |
 | `config log view [--lines N] [--no-follow]` | Tail the log file |

{hap_cli-0.8.20 → hap_cli-0.8.22}/hap_cli/README_CN.md

@@ -226,7 +226,7 @@ hap --json worksheet record list WORKSHEET_ID
 | `chat list` | 最近会话 |
 | `chat messages` | 单聊 / 群聊 / 收件箱（系统、应用、工作流等） |
 | `chat files` | 聊天中分享的文件 |
-| `chat send` | 向一个或多个用户发送纯文本消息 |
+| `chat send-to-one` | 向一个或多个用户发消息（单聊），可带附件 `--file`（文件作为聊天附件送达，不是链接） |
 | `chat group-info` | 群组信息 |
 | `chat card-detail` | 解析消息中嵌入的卡片引用 |
 
@@ -243,13 +243,21 @@ hap --json worksheet record list WORKSHEET_ID
 | `icon search` | 按中英文关键词搜索图标（多关键词取并集，命中越多排越前）；命中不足 10 个时随机补足推荐；无关键词列出全部 |
 | `icon list [-n SIZE] [-p PAGE]` | 分页列出图标及其关键词（默认每页 50 个） |
 
+### attachment — 已存储文件
+
+| 命令 | 说明 |
+|---|---|
+| `attachment share ADDRESS` | 为已存储的文件生成一条可以转给别人的链接（`--hours`，默认 48 小时） |
+
+> ADDRESS 传文件的链接即可——**已经失效的链接照样能传，原样粘贴**——也可以只传路径部分。文件本身不会过期，过期的只是链接，所以失效链接随时可以重新生成。
+
 ### upload — 文件上传
 
 | 命令 | 说明 |
 |---|---|
-| `upload [SOURCES...]` | 上传本地路径或 http(s) 直链到文件存储，返回中性的「已上传文件描述符」（fileID/key/url/serverName/filePath/fileName/fileExt/originalFileName/fileSize） |
+| `upload [SOURCES...]` | 上传本地路径或 http(s) 直链到文件存储，返回中性的「已上传文件描述符」（fileID/key/url/urlExpiresAt/serverName/filePath/fileName/fileExt/originalFileName/fileSize） |
 
-> 跨功能的通用能力——同一份描述符可用于工作表附件字段、聊天、动态、日程、评论等。用 `--files '[{"name":"封面.png","url":"https://..."}]'` 指定显示名；`--worksheet-id` / `--app-id` 优化上传 token 路由。
+> 跨功能的通用能力——同一份描述符可用于工作表附件字段、动态、日程、评论等。返回的 `url` 只是给你自己临时取用的地址，到 `urlExpiresAt` 就失效，不要发给别人；要把文件给别人，请用对应的附件入口，例如 `hap chat send-to-one --file <路径>`。用 `--files '[{"name":"封面.png","url":"https://..."}]'` 指定显示名；`--worksheet-id` / `--app-id` 优化上传 token 路由。
 
 ### config — 本地 CLI 配置
 
@@ -258,6 +266,7 @@ hap --json worksheet record list WORKSHEET_ID
 | `config show` | 显示 CLI 配置摘要 |
 | `config completion [bash\|zsh\|fish] [--install]` | 启用 `<Tab>` 补全 |
 | `config language [LANG]` | 切换显示语言（`en` / `zh-Hans` / `zh-Hant` / `ja`） |
+| `config update [auto\|notify\|off]` | 自动升级开关；`notify` 只提示不安装，`off` 不检查 |
 | `config log on / off / status` | 日志开关与状态 |
 | `config log level LEVEL` | 设置日志级别（`DEBUG/INFO/WARNING/ERROR/CRITICAL`） |
 | `config log view [--lines N] [--no-follow]` | 跟踪日志文件 |

{hap_cli-0.8.20 → hap_cli-0.8.22}/hap_cli/__init__.py

@@ -1,3 +1,3 @@
 """CLI harness for Mingdao HAP (hap-cli)."""
 
-__version__ = "0.8.20"
+__version__ = "0.8.22"

hap_cli-0.8.22/hap_cli/commands/attachment_cmd.py

@@ -0,0 +1,44 @@
+"""CLI commands for files stored as attachments."""
+
+import click
+
+from hap_cli.context import pass_context
+from hap_cli.core import attachment as attachment_mod
+from hap_cli.utils.formatting import output_json
+from hap_cli.i18n import t
+
+
+@click.group("attachment", help=t("Files stored as attachments."))
+def attachment():
+    """Attachment group."""
+
+
+@attachment.command("share")
+@click.argument("address")
+@click.option(
+    "--hours", type=int, default=attachment_mod.DEFAULT_SHARE_HOURS,
+    show_default=True, help="How long the link stays usable.",
+)
+@pass_context
+def attachment_share(ctx, address, hours):
+    """Create a link to a stored file that you can pass on.
+
+    \b
+      hap attachment share https://doc.example.com/doc/20260830/abc.html
+      hap attachment share doc/20260830/abc.html --hours 168
+
+    ADDRESS is the file's link — a link that has already stopped working
+    is fine, paste it as-is — or just the path part of it.
+    """
+    try:
+        session = ctx.get_session()
+        data = attachment_mod.share_url(session, address, hours=hours)
+        ctx.output(data, _human)
+    except Exception as e:
+        ctx.handle_error(e)
+
+
+def _human(d):
+    click.echo(d["url"])
+    if d.get("expiresAt"):
+        click.echo(f"Usable until {d['expiresAt']}")

{hap_cli-0.8.20 → hap_cli-0.8.22}/hap_cli/commands/chat_cmd.py

@@ -6,6 +6,7 @@ import click
 
 from hap_cli.context import pass_context
 from hap_cli.core import chat as chat_mod
+from hap_cli.core import upload as upload_mod
 from hap_cli.utils.formatting import output_json, output_table
 from hap_cli.i18n import t
 
@@ -251,19 +252,64 @@ def chat_messages(
 
 @chat.command("send-to-one")
 @click.option("--to", "-t", multiple=True, help="Target user account ID (can repeat)")
-@click.option("--message", "-m", required=True, help="Message content")
+@click.option("--message", "-m", default="", help="Message text")
+@click.option(
+    "--file", "-f", "files", multiple=True,
+    help="Attach a file: a local path or an http(s) address. Repeat for "
+         "several. The file arrives as an attachment the recipient can "
+         "open at any time, not as a link that stops working.",
+)
+@click.option(
+    "--dry-run", is_flag=True, default=False,
+    help="Show what would be sent, without uploading or sending anything.",
+)
 @pass_context
-def chat_send_to_one(ctx, to, message):
-    """Send a plain-text message to one or more users (1-on-1)."""
+def chat_send_to_one(ctx, to, message, files, dry_run):
+    """Send a message, optionally with files, to one or more users (1-on-1).
+
+    \b
+      hap chat send-to-one -t <accountId> -m "spec attached" -f ./spec.pdf
+
+    Text and each file arrive as separate messages, in that order. You
+    cannot message yourself — your own account is skipped.
+    """
     if not to:
         ctx.handle_error(click.UsageError(
             "Provide at least one --to <accountId>."
         ))
         return
+    if not message and not files:
+        ctx.handle_error(click.UsageError(
+            "Provide --message, --file, or both."
+        ))
+        return
+    sources = upload_mod.source_descriptors(list(files))
+    if dry_run:
+        ctx.output(
+            {"to": list(to), "message": message, "files": list(files),
+             "sent": False},
+            lambda d: click.echo(
+                "Dry run — nothing sent."
+                + f"\n  To:      {', '.join(to)}"
+                + (f"\n  Message: {message}" if message else "")
+                + "".join(f"\n  File:    {f}" for f in files)
+            ),
+        )
+        return
     try:
         session = ctx.get_session()
-        data = chat_mod.send_message(session, list(to), message)
-        ctx.output(data, lambda d: click.echo("Message sent."))
+        if not sources:
+            data = chat_mod.send_message(session, list(to), message)
+            ctx.output(data, lambda d: click.echo("Message sent."))
+            return
+        descriptors = chat_mod.upload_chat_files(session, sources)
+        acks = chat_mod.send_files(session, list(to), descriptors, message)
+        ctx.output(
+            {"sent": len(acks), "files": len(descriptors), "acks": acks},
+            lambda d: click.echo(
+                f"Sent {len(descriptors)} file(s) to {len(to)} recipient(s)."
+            ),
+        )
     except Exception as e:
         ctx.handle_error(e)
 

{hap_cli-0.8.20 → hap_cli-0.8.22}/hap_cli/commands/config_cmd.py

@@ -122,6 +122,8 @@ def config_completion(shell, install):
 @pass_context
 def config_show(ctx):
     """Display current harness configuration."""
+    from hap_cli.core.update import get_update_mode
+
     log_cfg = load_logging_config()
     data = {
         "logging": {
@@ -129,6 +131,7 @@ def config_show(ctx):
             "level": log_cfg["level"],
             "file": str(resolve_log_path(log_cfg)),
         },
+        "update": get_update_mode(),
     }
 
     def _human(d):
@@ -136,6 +139,7 @@ def config_show(ctx):
         click.echo(f"  enabled : {d['logging']['enabled']}")
         click.echo(f"  level   : {d['logging']['level']}")
         click.echo(f"  file    : {d['logging']['file']}")
+        click.echo(f"update    : {d['update']}")
 
     ctx.output(data, _human)
 
@@ -205,6 +209,46 @@ def log_status(ctx):
     _echo_log_status(ctx, cfg)
 
 
+# ── `hap config update` ───────────────────────────────────────────────────
+
+
+@config.command("update")
+@click.argument(
+    "mode", required=False, type=click.Choice(["auto", "notify", "off"]),
+)
+@pass_context
+def config_update(ctx, mode):
+    """Control whether hap-cli upgrades itself.
+
+    \b
+      auto    check hourly and install new versions (default)
+      notify  check hourly and tell you, but never install
+      off     never check
+
+    Use ``notify`` or ``off`` to pin the version in scripted or
+    production environments. Without an argument, shows the current
+    setting. ``hap update`` still upgrades on demand in every mode.
+    """
+    from hap_cli.core.session import load_config, save_config
+    from hap_cli.core.update import get_update_mode
+
+    if mode is None:
+        current = get_update_mode()
+        if ctx.json_mode:
+            from hap_cli.utils.formatting import output_json
+            output_json({"update": current})
+        else:
+            click.echo(f"Self-update: {current}")
+        return
+
+    save_config({"update": mode})
+    if ctx.json_mode:
+        from hap_cli.utils.formatting import output_json
+        output_json({"status": "ok", "update": mode})
+    else:
+        click.echo(f"Self-update set to: {mode}")
+
+
 # ── `hap config language` ─────────────────────────────────────────────────
 
 

{hap_cli-0.8.20 → hap_cli-0.8.22}/hap_cli/commands/upload_cmd.py

@@ -10,7 +10,13 @@ from hap_cli.utils.formatting import output_json
 from hap_cli.i18n import t
 
 
-@click.command("upload", help=t("Upload file(s) to the file store."))
+@click.command("upload", help=t(
+    "Upload file(s) to the file store.\n\n"
+    "The returned \"url\" is a temporary address for your own immediate "
+    "use and stops working at the moment shown in \"urlExpiresAt\". Do not "
+    "send it to anyone — to share a file, attach it where it belongs, "
+    "e.g. 'hap chat send-to-one --file <path>'."
+))
 @click.argument("sources", nargs=-1)
 @click.option("--files", "files_json", default="",
               help="JSON array of {name,url} or {name,path} descriptors "
@@ -33,18 +39,18 @@ def upload(ctx, sources, files_json, worksheet_id, app_id):
     originalFileName/fileSize) is returned. Consumers wrap these for their
     own attachment shape — e.g. a worksheet Attachment field, a chat
     message, a post, a comment, or a calendar event.
+
+    The returned "url" is a temporary address for your own immediate use
+    and stops working at the moment shown in "urlExpiresAt". Do not send
+    it to anyone — to share a file, attach it where it belongs, e.g.
+    'hap chat send-to-one --file <path>'.
     """
     try:
         session = ctx.get_session()
         if files_json:
             files = json.loads(files_json)
         else:
-            files = []
-            for s in sources:
-                if s.startswith("http://") or s.startswith("https://"):
-                    files.append({"url": s})
-                else:
-                    files.append({"path": s})
+            files = upload_mod.source_descriptors(sources)
         if not files:
             raise click.UsageError("provide SOURCES or --files")
         descriptors = upload_mod.upload_files(

{hap_cli-0.8.20 → hap_cli-0.8.22}/hap_cli/core/action_spec_adapter.py

@@ -110,9 +110,15 @@ def build_button_payload(spec: dict[str, Any]) -> dict[str, Any]:
         # in the UI; for the dedicated 二次确认 button use clickType 2.
         if out["clickType"] == 1 and confirm:
             out["clickType"] = 2
-        out["confirmMsg"] = confirm_msg or "你确认执行此操作吗？"
-        out["sureName"] = spec.get("sureName", "确认")
-        out["cancelName"] = spec.get("cancelName", "取消")
+        # Dialog text is stored on the button itself, so it must be
+        # written in the application's language, not ours. Follows the
+        # active CLI language; an explicit value always wins.
+        from hap_cli.i18n import content_default
+
+        out["confirmMsg"] = confirm_msg or content_default("button.confirmMsg")
+        out["sureName"] = spec.get("sureName") or content_default("button.sure")
+        out["cancelName"] = (
+            spec.get("cancelName") or content_default("button.cancel"))
 
     # enableWhen → filters (reuse the shared filter translator).
     enable_when = spec.get("enableWhen")

hap_cli-0.8.22/hap_cli/core/attachment.py

@@ -0,0 +1,107 @@
+"""Attachments in the file store: shareable links for stored files.
+
+The address handed out at upload time is a private-bucket signature that
+expires within the hour (``upload.url_expires_at``). The file behind it
+does not expire — the object path *is* the URL path — so a dead link is
+re-signable at any time.
+
+``Attachment/GetShareLocalAttachmentUrl`` is what the web UI's
+"分享附件" action calls: pd-openweb
+src/components/shareAttachment/toMobile.js:121 passes
+``{filePath: file.qiniuPath, hours: 48}``, where ``qiniuPath`` is built
+as ``window.config.FilePath + file.key``
+(src/pages/chat/components/Message/MessageToolbar/index.js:222).
+
+That prefix is not decorative. Verified live on 2026-08-31, the server
+accepts the ``config.FilePath`` form and nothing else — a bare key, a
+``documentHost``-prefixed URL, or the original signed URL with its query
+intact each come back as an empty string with no error state. So this
+module normalizes any address the user has to hand down to a key and
+rebuilds the one prefix that works.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+from urllib.parse import urlparse
+
+from hap_cli.core.session import APIError, Session, SessionError
+
+logger = logging.getLogger("hap_cli.attachment")
+
+# What the web UI uses when it shares an attachment (toMobile.js:123).
+DEFAULT_SHARE_HOURS = 48
+
+
+def store_key(address: str) -> str:
+    """Reduce any form of a stored file's address to its store key.
+
+    Accepts a full URL on any of the store's hosts (with or without the
+    ``?e=…&token=…`` signature still attached — a dead link pasted out of
+    a chat message is the common case), a leading-slash path, or a bare
+    key.
+    """
+    if not address or not address.strip():
+        raise ValueError("a file address or key is required")
+    address = address.strip()
+    if "://" in address:
+        address = urlparse(address).path
+    else:
+        # A bare key may still carry a query if it came from a copied link.
+        address = address.split("?", 1)[0]
+    return address.lstrip("/")
+
+
+def _file_path_prefix(session: Session) -> str:
+    """The store prefix this endpoint requires in ``filePath``.
+
+    Bootstrap publishes it as ``config.FilePath`` — the same value chat
+    file addresses are built from (``chat.chat_file_host``).
+    """
+    meta = session.get_global_meta()
+    for scope in (meta.get("config"), meta):
+        if isinstance(scope, dict) and scope.get("FilePath"):
+            return scope["FilePath"]
+    raise SessionError(
+        "This server did not publish a file address, so a link cannot be "
+        "created. Check that you are signed in to the right server, then "
+        "try again."
+    )
+
+
+def share_url(
+    session: Session,
+    address: str,
+    *,
+    hours: int = DEFAULT_SHARE_HOURS,
+) -> dict[str, Any]:
+    """Create a fresh, time-limited link to a file already in the store.
+
+    ``address`` is anything that identifies the file: its current or
+    expired link, or its bare key. Returns
+    ``{url, expiresAt, hours, key}``.
+    """
+    from hap_cli.core.upload import _iso, url_expires_at
+
+    if hours <= 0:
+        raise ValueError("hours must be a positive number")
+    key = store_key(address)
+    prefix = _file_path_prefix(session)
+    url = session.api_call(
+        "Attachment", "GetShareLocalAttachmentUrl",
+        {"filePath": prefix + key, "hours": hours},
+    )
+    if not url or not isinstance(url, str):
+        # An unknown or unreachable file is answered with an empty string
+        # and a success state, so there is nothing to detect but this.
+        logger.warning("GetShareLocalAttachmentUrl returned %r for key=%s", url, key)
+        raise APIError(
+            "Could not create a link for that file. Check the address is "
+            "complete and that the file still exists."
+        )
+    return {
+        "url": url,
+        "expiresAt": _iso(url_expires_at(url)),
+        "hours": hours,
+        "key": key,
+    }