# SHIRE Marketing Forge Easy v1.3.0

A local, approval-gated SHIRE3D workflow:

**Approved SHIRE3D stores → every live product → customer-friendly monthly marketing → Ray reviews → official account login → controlled publishing queue**

Kitchen Hero remains completely separate.

## The one-product mode is gone

New campaigns cannot select one product. SHiRE always:

- reads the live product shelf populated from the three approved SHIRE3D stores;
- includes every marketable product in the campaign;
- gives each product at least one feature before anything repeats;
- expands the post count when the catalogue is larger than the chosen monthly pace;
- ranks less-promoted products earlier;
- uses the matching product name, image, price, description and shop link;
- rotates the catalogue across Facebook, Instagram, LinkedIn, TikTok and YouTube Shorts;
- skips demo, paused, unavailable, sold-out and discontinued products.

The Prepare screen contains no product dropdown, no single-item radio button and no hidden single-product control. It shows a locked **EVERY ITEM** summary and the exact count of included products.

## Product autopilot sources

The local server has a fixed read-only allowlist for:

- `https://shire3d.com/`
- `https://shire3d.com.au/s/shop`
- `https://www.etsy.com/au/shop/Shire3D`, the working destination for `shire3d.etsy.com`

The Forge checks due sources when it starts and checks again every 30 minutes. A source is refreshed no more than once every six hours unless Ray presses **Sync now**.

Public listing names, descriptions, prices, images, availability and links can be added or refreshed. Matching store listings are grouped instead of duplicated, and direct SHIRE3D store data is preferred over marketplace copies.

## Social account screen

The new **Accounts** screen supports official OAuth authorization for:

- Facebook
- Instagram
- LinkedIn
- TikTok
- YouTube Shorts through the YouTube Data API

The Forge never asks for a social password. Sign-in happens on the platform's own consent screen.

Every platform first requires a developer application controlled by Ray. The included Windows helper stores the developer Client ID/App ID and encrypts the developer secret using Windows DPAPI for the current Windows user. On Linux, values can be loaded through a local environment file that is excluded by `.gitignore`.

OAuth access and refresh tokens are held in the local Node server's memory only in v1.3.0. They are not written into browser storage, exports, the catalogue cache or the source folder, and they disappear when the Forge server closes. This means reconnecting may be required after a restart.

Read `SOCIAL-ACCOUNT-SETUP.md` for callback addresses and setup order.

## What account connection does not do

Connecting an account does not:

- approve a campaign;
- change draft wording;
- publish anything automatically;
- bypass the global pause or emergency stop;
- allow Kitchen Hero access;
- import customers, messages, orders, contacts or private analytics.

Real platform publishing is deliberately not enabled in this package. Each platform has its own posting permissions, app review and media requirements. v1.3.0 establishes the official login bridge and keeps the existing queue in controlled test mode until those approvals and platform-specific publishers are implemented and separately verified.

## Start on Windows

1. Extract the full ZIP into a new folder.
2. Double-click `start-windows.bat`.
3. Confirm the sidebar says **Easy Mode · v1.3.0**.
4. Open Products and sync the catalogue.
5. Open SHiRE prepares and confirm the **EVERY ITEM** card.

The start script checks the server version. If an older Forge is still listening on `127.0.0.1:4173`, it stops that process and starts v1.3.0. This fixes the common case where a new ZIP was extracted but the browser continued showing the old one-product interface.

The v1.3 service worker uses network-first loading and removes earlier caches. Static files are no longer allowed to keep an older interface in front of the current local server.

## Configure social login on Windows

1. Complete the developer-app steps in `SOCIAL-ACCOUNT-SETUP.md`.
2. Double-click `configure-social-logins-windows.ps1`.
3. Enter only the developer App ID/Client ID and developer secret.
4. Restart `start-windows.bat`.
5. Open Accounts and choose **Sign in with ...**.

The configuration helper creates `social-oauth.secure.json`. It is intentionally excluded from Git and should never be shared in support screenshots, ZIP files or backups.

## Linux / ARMOR OS

Copy the example without committing it:

```bash
cp social-oauth.env.sh.example social-oauth.env.sh
chmod 600 social-oauth.env.sh
```

Fill only the developer values you intend to use, then run:

```bash
./start-linux.sh
```

## Approval and queue protections

- Generated posts begin in Ray review.
- Ray's campaign approval freezes the exact caption, media, platform, date, time and account into a queue record.
- Editing a frozen post invalidates approval and cancels its affected queue job.
- Rejected posts are excluded from approval.
- Duplicate publishing records are blocked.
- Publishing starts paused.
- Emergency stop overrides every job.
- v1.3.0 queue release remains sandbox/test-only and contacts no social posting API.

## Data boundary

The product sync reads public SHIRE3D storefront data only. Social OAuth sends the browser to the selected platform and returns an authorization code to the localhost callback.

The Forge does not request or import:

- Kitchen Hero repositories, users, recipes, households, branding, analytics, Stripe or subscription data;
- SHIRE3D customer details, orders, addresses, messages or payment records;
- social account passwords;
- arbitrary websites outside the product allowlist.

`server.js` binds to `127.0.0.1` only, not the LAN or public internet.

## Backups

Use **Advanced → Download full JSON** for products and campaign records. Developer secrets and OAuth tokens are intentionally absent from the export.

`catalog-cache.json` contains only public storefront results and timestamps. It can be deleted safely.

## Tests

```bash
npm test
```

Expected result:

```text
PASS: SHIRE Marketing Forge Easy core safety tests
PASS: customer-friendly full-catalogue marketing tests
PASS: website catalog sync tests
PASS: website parser tests
PASS: official OAuth bridge safety tests
```

## Practical platform limits

Storefront layouts may change or temporarily block automated access, especially Etsy. The product screen reports the real source error and never fabricates products.

Social login and posting capabilities are governed by each platform. A successful OAuth login does not guarantee that a developer app has been approved for Page, organisation, video or content-publishing permissions. The Accounts screen therefore distinguishes **one-time setup**, **ready to login** and **connected** states instead of pretending that a platform is ready.
