hap-cli 0.8.21__tar.gz → 0.8.23__tar.gz

{hap_cli-0.8.21 → hap_cli-0.8.23}/MANIFEST.in

@@ -11,8 +11,5 @@ include sources/v3-api-schema/INDEX.json
 include hap_cli/README.md
 include hap_cli/README_CN.md
 recursive-include hap_cli/locale *.json
-
-# edit-spec schemas are canonical in the hap-cli-app-editor skill; ship them
-# in the sdist so setup.py's build step can mirror them into
-# hap_cli/core/editor/editspec/ for the ``hap app-editor`` runtime loader.
-recursive-include skills/cli/hap-cli-app-editor/scripts/editspec *.json
+include hap_cli/guide/index.json
+recursive-include hap_cli/guide *.md

{hap_cli-0.8.21 → hap_cli-0.8.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hap-cli
-Version: 0.8.21
+Version: 0.8.23
 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,27 @@ 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.
+
+### guide — built-in usage guide
+
+| Command | Description |
+|---|---|
+| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong (`hap guide <topic>` for detail) |
+
 ### 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
 

{hap_cli-0.8.21/hap_cli → hap_cli-0.8.23}/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,27 @@ 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.
+
+### guide — built-in usage guide
+
+| Command | Description |
+|---|---|
+| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong (`hap guide <topic>` for detail) |
+
 ### 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
 

{hap_cli-0.8.21 → hap_cli-0.8.23/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,27 @@ 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.
+
+### guide — built-in usage guide
+
+| Command | Description |
+|---|---|
+| `guide` | Built-in usage guide: what this version can do, and the value formats that are easy to get wrong (`hap guide <topic>` for detail) |
+
 ### 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
 

{hap_cli-0.8.21 → hap_cli-0.8.23}/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,27 @@ hap --json worksheet record list WORKSHEET_ID
 | `icon search` | 按中英文关键词搜索图标（多关键词取并集，命中越多排越前）；命中不足 10 个时随机补足推荐；无关键词列出全部 |
 | `icon list [-n SIZE] [-p PAGE]` | 分页列出图标及其关键词（默认每页 50 个） |
 
+### attachment — 已存储文件
+
+| 命令 | 说明 |
+|---|---|
+| `attachment share ADDRESS` | 为已存储的文件生成一条可以转给别人的链接（`--hours`，默认 48 小时） |
+
+> ADDRESS 传文件的链接即可——**已经失效的链接照样能传，原样粘贴**——也可以只传路径部分。文件本身不会过期，过期的只是链接，所以失效链接随时可以重新生成。
+
+### guide — 内置使用指南
+
+| 命令 | 说明 |
+|---|---|
+| `guide` | 内置使用指南：当前版本能做什么、哪些取值格式容易写错（`hap guide <主题>` 看细节） |
+
 ### 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 配置
 

{hap_cli-0.8.21 → hap_cli-0.8.23}/hap_cli/__init__.py

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

hap_cli-0.8.23/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.21 → hap_cli-0.8.23}/hap_cli/commands/auth_cmd.py

@@ -30,7 +30,11 @@ SERVER_HELP = (
 )
 
 
-@click.group(help=t('Manage authentication and session identity.'))
+@click.group(help=t(
+    'Manage authentication and session identity.\n\n'
+    'Signing in, keeping several environments and accounts, and choosing the '
+    'current organization are walked through in `hap guide setup`.'
+))
 def auth():
     pass
 

{hap_cli-0.8.21 → hap_cli-0.8.23}/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
 
@@ -72,7 +73,11 @@ def _output_chat_list_table(rows):
     )
 
 
-@click.group(help=t('Chat and messaging management.'))
+@click.group(help=t(
+    'Chat and messaging management.\n\n'
+    'To follow a notification back to the app record it belongs to, see '
+    '`hap guide messages`.'
+))
 def chat():
     pass
 
@@ -251,19 +256,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.23/hap_cli/commands/guide_cmd.py

@@ -0,0 +1,36 @@
+"""CLI command for the built-in usage guide."""
+
+import click
+
+from hap_cli.context import pass_context
+from hap_cli.core import guide as guide_mod
+from hap_cli.i18n import t
+
+
+@click.command("guide")
+@click.argument("topic", required=False)
+@pass_context
+def guide(ctx, topic):
+    """How to use this tool: what it can do, and how to get the values right.
+
+    \b
+      hap guide            what hap can do, and which topics go deeper
+      hap guide record     writing records: what value each field type wants
+
+    Run this before composing commands — it describes the version of hap
+    installed on this machine, so it never disagrees with what you get.
+    """
+    try:
+        from hap_cli.hap_cli import cli as root
+
+        if topic:
+            body = guide_mod.render_topic(topic)
+            ctx.output({"topic": topic, "text": body},
+                       lambda d: click.echo(d["text"]))
+            return
+        payload = guide_mod.overview_payload(root)
+        ctx.output(payload, lambda d: click.echo(d["text"]))
+    except guide_mod.UnknownTopic as e:
+        ctx.handle_error(e)
+    except Exception as e:
+        ctx.handle_error(e)

{hap_cli-0.8.21 → hap_cli-0.8.23}/hap_cli/commands/record_cmd.py

@@ -90,6 +90,10 @@ def record_create(ctx, worksheet_id, field, fields_json, no_workflow):
 
     Pass values either as repeated -f CONTROL_ID=VALUE pairs or as one
     --fields-json array.
+
+    What to put in a value depends on the field type, and a wrong shape is
+    usually accepted and stored broken rather than rejected — see
+    `hap guide record` before writing, and read the record back after.
     """
     if field and fields_json:
         raise click.UsageError("Pass exactly one of -f or --fields-json.")
@@ -162,6 +166,10 @@ def record_update(ctx, worksheet_id, row_id, field, fields_json, no_workflow):
     fields change), a child row without a "rowid" adds a new row, and a
     child row with "_delete": true removes that row. Rows you don't list
     are left untouched. An empty list (or null) clears the sub-table.
+
+    Every other field type replaces rather than merges: passing a new value
+    for a multi-select, attachment or relation field drops whatever was
+    there. Value formats per field type are in `hap guide record`.
     """
     if field and fields_json:
         raise click.UsageError("Pass exactly one of -f or --fields-json.")

{hap_cli-0.8.21 → hap_cli-0.8.23}/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.21 → hap_cli-0.8.23}/hap_cli/commands/worksheet_cmd.py

@@ -11,7 +11,12 @@ from hap_cli.utils.options import org_id_option, require_api_project_id
 from hap_cli.i18n import t
 
 
-@click.group(help=t('Worksheet operations.'))
+@click.group(help=t(
+    'Worksheet operations.\n\n'
+    'Writing records: the value each field type expects (options, members, '
+    'relations, sub-tables, attachments) is covered by `hap guide record` — '
+    'a wrong shape is usually accepted and stored broken.'
+))
 def worksheet():
     pass
 

hap_cli-0.8.23/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,
+    }