=== Developer Embeds ===
Contributors: declanchidlow
Donate link: https://vale.rocks/support
Tags: npm, pypi, github, gitlab, embeds
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Embed rich, customisable cards for npm, PyPI, and repositories on GitHub, GitLab, and other forges. Perfect for blog posts or documentation.

== Description ==

Developer Embeds adds three editor blocks for live package and repository details:

* npmx Package Card - npm package version, size, downloads, licence, and other metadata.
* PyPI Package Card - Python package details from PyPI.
* Repository Card - repository details from GitHub, GitLab, Gitea, Forgejo, Codeberg, Bitbucket, Tangled, SourceHut, Azure DevOps, or a self-hosted forge.

Each block has controls for the package or repository, version or branch, visible details, and component-specific options. The same components are available as shortcodes for the classic editor, widgets, and templates:

[npmx-card package="npmx-embed"]
[pypi-card package="requests"]
[repo-card repo="tangled:vale.rocks/developer-embeds"]

On the front end, component scripts load only when an embed is present and a small stylesheet is loaded site-wide. The cards are rendered by bundled web components and can be themed with CSS custom properties. No API keys or configuration are required.

The plugin makes client-side requests to public APIs only when an embed is displayed or previewed. See External Services below. This plugin is not affiliated with npm, npmx, PyPI, the Python Software Foundation, or any supported repository forge.

== Screenshots ==

1. Three embed blocks in the editor, with the Repository Card settings panel open.

== Installation ==

1. Upload the plugin zip through Plugins > Add New > Upload Plugin, or install it from the WordPress plugin directory.
2. Activate the plugin.
3. Add a card block from the Embed category, or use the shortcodes above.

== Frequently Asked Questions ==

= Do the cards require JavaScript? =
Yes. The cards are rendered by the bundled web components and fetch their data in the browser.

= Does this work with the classic editor? =
Yes. Use the shortcode form.

= Can I use a self-hosted or custom forge? =
Yes. Set the Host and API URL fields on the Repository Card, or use the host and api shortcode attributes.

= Why does a repository card sometimes show a rate-limit error? =
Forges often limit unauthenticated requests per IP address. If the limit is reached, wait and try again later.

== Support ==

Support is provided through the WordPress.org support forum for this plugin.

== External Services ==

The plugin itself does not collect, store, or share personal data, and does not set cookies or use analytics. Requests are made by the visitor's browser, and by an administrator's browser when previewing an embed in the editor, only when an embed is displayed. API responses are cached in sessionStorage for 15 minutes.

* npmx Package Card: the package name and version are sent to the [npm registry](https://registry.npmjs.org/) and [npm downloads API](https://api.npmjs.org/). See npm's [privacy policy](https://www.npmjs.com/policies/privacy) and [terms](https://www.npmjs.com/policies/terms).
* PyPI Package Card: the package name and version are sent to [PyPI](https://pypi.org/), and the package name is sent to [Shields.io](https://shields.io/) for download counts. See PyPI's [terms](https://pypi.org/policy/terms-of-use/), the [Python Software Foundation privacy policy](https://www.python.org/privacy/), and [Shields.io's privacy policy](https://shields.io/privacy).
* Repository Card: the repository path, branch, and optional custom host or API URL are sent to the selected forge. Supported public forges include [GitHub](https://api.github.com/), [GitLab](https://gitlab.com/api/v4/), [Bitbucket](https://api.bitbucket.org/), Gitea, Forgejo, Codeberg, [Tangled](https://api.tangled.org/), SourceHut, and Azure DevOps. Tangled handle resolution also contacts [Bluesky's public API](https://public.api.bsky.app/); GitHub repository preview images are loaded from [opengraph.githubassets.com](https://opengraph.githubassets.com/).
* Privacy policies for the main services: [GitHub](https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement), [GitLab](https://about.gitlab.com/privacy/), [Bitbucket/Atlassian](https://www.atlassian.com/legal/privacy-policy), [Tangled](https://tangled.org/privacy), [Bluesky](https://bsky.social/about/support/privacy-policy), [SourceHut](https://man.sr.ht/privacy.md), [Codeberg](https://codeberg.org/Codeberg/org/src/branch/main/PrivacyPolicy.md), and [Azure DevOps](https://privacy.microsoft.com/privacystatement).
* Custom hosts: if you configure a custom host or API URL, the browser contacts that host directly; the site owner is responsible for that service's privacy policy. These services may receive the browser's IP address and the requested package or repository details.

== Source Code ==

The plugin source and bundled web components are included in readable form. Component repositories: [npmx-embed](https://tangled.org/vale.rocks/npmx-embed), [pypi-embed](https://tangled.org/vale.rocks/pypi-embed), and [repository-embed](https://tangled.org/vale.rocks/repository-embed). From the project repository, build with `cd WordPress && npm install && npm run package`; the zip is written to `build/developer-embeds.zip`.

The plugin is licensed under GPLv2 or later. The bundled components are MIT licensed; their license texts are included in `licenses/`.

== Changelog ==

= 0.1.0 =
* Initial release.