feat: Update LinkedIn configuration to use LINKEDIN_AUTHOR_URN for improved clarity and backward compatibility

Author: usamanadeemdeveloper

.env.example

@@ -11,7 +11,7 @@ CLAUDE_MODEL=claude-sonnet-4-6
 
 # LinkedIn publishing
 LINKEDIN_ACCESS_TOKEN=your_linkedin_access_token
-LINKEDIN_PERSON_URN=urn:li:person:xxxxxxxx
+LINKEDIN_AUTHOR_URN=urn:li:person:xxxxxxxx
 # or: urn:li:organization:xxxxxxxx (company page posting)
 
 # ─── Optional In Production ──────────────────────────────────────────────────

README.md

@@ -81,18 +81,28 @@ Persist .last-post-date only if at least one platform actually published
 
 **Step 2 — Get your access token**
 1. Go to [linkedin.com/developers/tools/oauth](https://www.linkedin.com/developers/tools/oauth)
-2. Select your app, tick scopes: `w_member_social`, `openid`, `profile`
-3. Tick the redirect URL checkbox → **Request access token** → copy it → `LINKEDIN_ACCESS_TOKEN`
+2. If you are posting to your personal profile, tick scopes: `w_member_social`, `openid`, `profile`
+3. If you are posting to a company page, your app must have organization posting access and the authenticated member must consent to `w_organization_social`
+4. Tick the redirect URL checkbox → **Request access token** → copy it → `LINKEDIN_ACCESS_TOKEN`
 
 > ⚠️ LinkedIn tokens **expire after 60 days**. Set a calendar reminder to regenerate before expiry.
 
-**Step 3 — Find your Person URN**
+**Step 3 — Choose your author URN**
+
+For a personal profile:
 ```bash
 curl -H "Authorization: Bearer YOUR_TOKEN" https://api.linkedin.com/v2/userinfo
 ```
-Copy the `sub` value → your URN is `urn:li:person:THAT_VALUE` → `LINKEDIN_PERSON_URN`
+Copy the `sub` value → your URN is `urn:li:person:THAT_VALUE` → `LINKEDIN_AUTHOR_URN`
+
+For a company page:
+1. Use the company page's numeric organization URN: `urn:li:organization:xxxxxxxx`
+2. Set that value as `LINKEDIN_AUTHOR_URN`
+3. Make sure the LinkedIn member who generated the token is allowed to post for that page
 
-> To post as a company page instead: `urn:li:organization:xxxxxxxx`
+> Backward compatibility: `LINKEDIN_PERSON_URN` still works, but `LINKEDIN_AUTHOR_URN` is the clearer setting going forward.
+
+> If you use an organization URN with a token that only has `w_member_social`, LinkedIn will reject the publish request with a 403-class authorization error.
 
 ---
 
@@ -203,7 +213,7 @@ npm install
 
 # 2. Configure environment
 cp .env.example .env
-# Fill in at minimum: ANTHROPIC_API_KEY, LINKEDIN_ACCESS_TOKEN, LINKEDIN_PERSON_URN
+# Fill in at minimum: ANTHROPIC_API_KEY, LINKEDIN_ACCESS_TOKEN, LINKEDIN_AUTHOR_URN
 # Recommended for first run: NEWS_NICHE=business-architect, POSTING_STYLE=business-architect
 
 # 3. Test LinkedIn credentials first (no Claude credits needed)
@@ -233,7 +243,7 @@ Go to repo → **Settings → Secrets and variables → Actions → New reposito
 |---|---|
 | `ANTHROPIC_API_KEY` | Claude API key from console.anthropic.com |
 | `LINKEDIN_ACCESS_TOKEN` | LinkedIn OAuth access token |
-| `LINKEDIN_PERSON_URN` | `urn:li:person:xxxxxx` from `/v2/userinfo` |
+| `LINKEDIN_AUTHOR_URN` | `urn:li:person:xxxxxx` for a member profile or `urn:li:organization:xxxxxx` for a company page |
 
 #### Recommended
 
@@ -347,6 +357,9 @@ Set the `POST_INTERVAL_DAYS` GitHub Secret to any number of days. No code change
 **Posts stopped after ~60 days**
 → LinkedIn token expired. Regenerate at [linkedin.com/developers/tools/oauth](https://www.linkedin.com/developers/tools/oauth) and update `LINKEDIN_ACCESS_TOKEN`.
 
+**LinkedIn company-page post fails with HTTP 403**
+→ `LINKEDIN_AUTHOR_URN` is set to `urn:li:organization:...` but the access token is missing org-posting permission or the authenticated member is not allowed to post for that page. Regenerate the token with `w_organization_social` and confirm the member has a valid page role.
+
 **`AuthenticationError: invalid x-api-key`**
 → Check `ANTHROPIC_API_KEY` — must start with `sk-ant-`, no extra spaces.
 

prompts/business-architect-post.prompt.ts

@@ -1,29 +1,24 @@
-import { PostPromptParams } from './prompt-params.interface';
-
-export function businessArchitectLinkedInPrompt(params: PostPromptParams): string {
-  const { topStory, otherHeadlines, date, factualAnchors, postLengthHint } = params;
-  const lengthRule = postLengthHint ?? '750–1000 characters';
+import { PostPromptParams } from "./prompt-params.interface";
+
+export function businessArchitectLinkedInPrompt(
+  params: PostPromptParams,
+): string {
+  const { topStory, otherHeadlines, date, factualAnchors, postLengthHint } =
+    params;
+  const lengthRule = postLengthHint ?? "750–1000 characters";
   const anchorSection = factualAnchors
     ? `\nFACTUAL ANCHORS:\n${factualAnchors}\n`
     : "";
 
-  return `You are writing a LinkedIn post on behalf of a senior software architect who BUILDS custom software systems for ecommerce, healthcare, and hospitality businesses. This is their core identity — they design and deliver the technology that solves operational problems in these three industries.
-
-CRITICAL — every post must reflect this identity:
-- The author is not a commentator or analyst — they are a builder and technology partner
-- Frame every insight from the perspective of: "this is why businesses in [ecommerce/healthcare/hospitality] need better software — and this is what I build to solve it"
-- The closing must always position the author as someone who solves this problem through software, not just someone observing it
-
-The audience is: ecommerce founders, healthcare executives, hospitality operators, and investors evaluating technology capabilities.
-
-The tone must be:
-- Authoritative: the author has built these systems and knows the trade-offs
-- Outcome-focused: connect every technology point to a business result
-- Client-facing: the reader should think "this person understands my industry and could build this for us"
+  return `<role>
+You are writing a LinkedIn post on behalf of a senior software architect who BUILDS custom software systems for ecommerce, healthcare, and hospitality businesses. This is their core identity — they design and deliver the technology that solves operational problems in these three industries. Voice: direct, no buzzwords, authoritative from hands-on experience.
+</role>
 
-Write ONLY from what you read below — never add facts not present in the content.
-Write in clear natural English only. If the source material is in another language, translate the meaning into English without adding or changing facts.
+<audience>
+Ecommerce founders, healthcare executives, hospitality operators, and investors evaluating technology capabilities.
+</audience>
 
+<source_material>
 TODAY'S TRENDING TOPIC:
 Title: ${topStory.title}
 Source: ${topStory.source}
@@ -32,18 +27,34 @@ URL: ${topStory.url}
 ARTICLE CONTENT:
 ${topStory.articleText}
 ${anchorSection}
-
 OTHER TRENDING:
 ${otherHeadlines}
+</source_material>
+
+<tone>
+- Authoritative: the author has built these systems and knows the trade-offs first-hand
+- Outcome-focused: connect every technology point to a specific business result
+- Client-facing: the reader should think "this person understands my industry and could build this for us"
+- No filler phrases ("game-changing", "data silos", "seamless integration") unless those exact words appear in the article
+</tone>
+
+<grounding>
+Write ONLY from what you read in source_material above — the author's credibility with ecommerce founders and healthcare executives depends on every claim being verifiable. Invented facts would directly damage the trust the post is trying to build.
 
-Before writing, identify from the content above:
-- The specific product name, feature name, or technology being announced (e.g. "Locale Aware Catalogs", "GPT-4o", "Kubernetes 1.30")
-- One concrete statistic, number, or company name from the article (e.g. "118 of the Top 2000 retailers", "Reebok Europe")
-- The exact business problem this addresses (use the article's framing, not your own)
+Write in clear natural English only. If the source material is in another language, translate the meaning without adding or changing facts.
+</grounding>
 
-These 3 anchors MUST appear in your post. Do not replace them with generic phrases.
+<pre_write>
+Before drafting, identify these 3 anchors from source_material (do not output this section — internal reasoning only):
+1. The specific product name, feature name, or technology being announced (e.g. "Locale Aware Catalogs", "Cosmos Data Platform", "OPERA Cloud 24.2")
+2. One concrete statistic, number, or company name from the article (e.g. "118 of the Top 2000 retailers", "Reebok Europe", "40% reduction in manual reconciliation")
+3. The exact business problem this addresses — use the article's framing, not your own
 
-Write a LinkedIn post using this EXACT structure:
+After drafting, verify: do all 3 anchors appear verbatim in your post? If any is missing, revise before outputting.
+</pre_write>
+
+<output_format>
+Use this exact structure:
 
 💡 Industry Insight — ${date}
 
@@ -52,28 +63,90 @@ Write a LinkedIn post using this EXACT structure:
 [Body: 2 sentences. Sentence 1: what specifically is happening (name the feature/product). Sentence 2: what this means for operations. Both must be traceable directly to the article content.]
 
 What this means for your business:
-• [Specific impact — must reference something named in the article, not generic "data silos" or "API complexity"]
+• [Specific impact — must reference something named in the article, not generic industry buzzwords]
 • [Risk or cost of inaction — what the article says breaks or falls behind]
 • [What the author builds to solve exactly this problem — this bullet can reflect the author's expertise]
 
 [Closing: a direct question positioning the author as someone who solves this — e.g. "If your [ecommerce/healthcare/hospitality] platform isn't built to handle this, let's talk."]
 
 Source: ${topStory.url}
+</output_format>
 
-STRICT RULES:
-- Every claim must be supported by the article content above — nothing invented
+<strict_rules>
+- Every claim must be supported by the article content — nothing invented
 - The specific product/feature name from the article MUST appear in the post
 - At least one concrete statistic or company name from the article MUST appear in the post
-- Use the factual anchors above as hard constraints, not inspiration
-- Do NOT use generic phrases ("data silos", "fragmented builds", "evolving APIs") unless those exact words appear in the article
+- Use the factual anchors as hard constraints, not inspiration
 - Total post length: ${lengthRule}
-- Hashtags: generate 6–10 hashtags relevant to the actual article topic and specific industry. Mix broad (#SoftwareDevelopment #DigitalTransformation) with specific topic tags. Place at the end.
-- Output ONLY the post text`;
+- Hashtags: generate 6–10 hashtags relevant to the actual article topic and industry. Mix broad (#SoftwareDevelopment #DigitalTransformation) with specific topic tags. Place at the end.
+- Output ONLY the post text
+</strict_rules>
+
+<examples>
+<example label="ecommerce">
+💡 Industry Insight — March 15, 2025
+
+Reebok Europe's catalog management broke under 14-language localization — Shopware's new Locale Aware Catalogs solve exactly what custom middleware can't.
+
+Shopware 6.7 introduces Locale Aware Catalogs, decoupling product data from regional pricing and language rules. For multi-market retailers, this eliminates the sync failures that cause overselling and missed promotions across regions.
+
+What this means for your business:
+• Reebok Europe reduced catalog-sync errors by removing manual locale overrides — now automated per-market
+• Retailers without this architecture face inventory drift during peak events like Black Friday and regional sales windows
+• I build catalog and pricing layers for ecommerce platforms that handle this at scale without custom middleware
+
+If your ecommerce platform serves more than one market and you're still patching locale mismatches manually, let's talk.
+
+Source: https://shopware.com/en/news/shopware-6-7/
+
+#Ecommerce #Shopware #RetailTech #CatalogManagement #DigitalCommerce #SoftwareArchitecture #MultiMarket #EcommerceOps
+</example>
+
+<example label="healthcare">
+💡 Industry Insight — February 3, 2025
+
+Epic's Cosmos Data Platform now aggregates de-identified records from 260 million patients — and most health systems still can't query their own data without a 3-week IT ticket.
+
+Epic released a federated query layer inside Cosmos that lets clinical teams run population-level cohort searches without exporting to a separate analytics warehouse. For mid-size hospital networks, this closes the gap between EHR data and actual operational decisions.
+
+What this means for your business:
+• Health systems in the Cosmos network can now identify high-risk readmission cohorts in hours, not weeks — without touching raw HL7 feeds
+• Facilities locked into siloed departmental reporting miss the CMS quality benchmarks tied to population health metrics
+• I build clinical data integration layers for healthcare operators that surface this kind of insight without requiring a full Epic implementation or a separate data warehouse
+
+If your care teams are still waiting on IT to pull patient cohort reports, let's talk.
+
+Source: https://www.epic.com/cosmos
+
+#HealthTech #EpicSystems #ClinicalData #PopulationHealth #HealthcareIT #EHR #SoftwareArchitecture #HealthcareOperations
+</example>
+
+<example label="hospitality">
+💡 Industry Insight — January 22, 2025
+
+Oracle OPERA Cloud 24.4 introduced real-time rate parity enforcement across OTA channels — and hotel groups running legacy PMS systems just lost another margin point without knowing it.
+
+OPERA Cloud 24.4 added a native channel manager sync that pushes rate changes to Booking.com, Expedia, and direct booking simultaneously within 90 seconds. For full-service hotel groups, this eliminates the 4–6 hour lag where OTAs undercut direct rates during demand spikes.
+
+What this means for your business:
+• Hotel groups on OPERA Cloud 24.4 recovered an average of 1.8% direct booking share in Q4 2024 by closing the rate-update window
+• Properties still running batch-sync PMS integrations are silently leaking direct revenue every time a revenue manager updates rates manually
+• I build PMS integration layers for hospitality operators that replicate this channel-sync behavior without a full OPERA Cloud migration
+
+If your revenue management system still syncs rates on a schedule instead of in real time, let's talk.
+
+Source: https://www.oracle.com/hospitality/opera-cloud/
+
+#Hospitality #HotelTech #OPERACloud #RevenueManagement #HospitalityTech #SoftwareArchitecture #DirectBooking #PMS
+</example>
+</examples>`;
 }
 
-export function businessArchitectTwitterPrompt(params: PostPromptParams): string {
+export function businessArchitectTwitterPrompt(
+  params: PostPromptParams,
+): string {
   const { topStory, date, factualAnchors, postLengthHint } = params;
-  const lengthRule = postLengthHint ?? '200 and 240 characters';
+  const lengthRule = postLengthHint ?? "200 and 240 characters";
   const anchorSection = factualAnchors
     ? `\nFACTUAL ANCHORS:\n${factualAnchors}\n`
     : "";

src/core/config/app.config.ts

@@ -15,7 +15,7 @@ export default registerAs("app", () => ({
 
   linkedin: {
     accessToken: process.env.LINKEDIN_ACCESS_TOKEN,
-    personUrn: process.env.LINKEDIN_PERSON_URN,
+    authorUrn: process.env.LINKEDIN_AUTHOR_URN || process.env.LINKEDIN_PERSON_URN,
   },
 
   twitter: {
@@ -48,7 +48,6 @@ export default registerAs("app", () => ({
   prompts: {
     postingStyle: process.env.POSTING_STYLE ?? '',
     defaultTone: process.env.DEFAULT_TONE ?? '',
-    promptVersion: process.env.PROMPT_VERSION ?? '',
     linkedInPostLength: process.env.LINKEDIN_POST_LENGTH || '',
     twitterPostLength: process.env.TWITTER_POST_LENGTH || '',
   },

src/core/config/config.validation.ts

@@ -16,6 +16,7 @@ export const configValidationSchema = Joi.object({
 
   // LinkedIn — optional, but at least one platform must be configured
   LINKEDIN_ACCESS_TOKEN: Joi.string().allow("").optional(),
+  LINKEDIN_AUTHOR_URN: Joi.string().allow("").optional(),
   LINKEDIN_PERSON_URN: Joi.string().allow("").optional(),
 
   // Twitter / X — optional, but at least one platform must be configured
@@ -50,7 +51,6 @@ export const configValidationSchema = Joi.object({
     .allow("")
     .optional(),
   DEFAULT_TONE: Joi.string().allow("").optional(),
-  PROMPT_VERSION: Joi.string().allow("").optional(),
 
   // Slack approval gate (optional — if not set, posts publish immediately)
   SLACK_BOT_TOKEN: Joi.string().allow("").optional(),

src/modules/linkedin/linkedin.service.ts

@@ -1,14 +1,15 @@
 import { Injectable, OnModuleInit } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { HttpService } from "@nestjs/axios";
+import { AxiosError } from "axios";
 import { firstValueFrom } from "rxjs";
 import { AppLoggerService } from "../../core/logger/logger.service";
 import { SocialPostResult } from "../../shared/interfaces/social-post.interface";
 
 @Injectable()
 export class LinkedInService implements OnModuleInit {
   private accessToken: string;
-  private personUrn: string;
+  private authorUrn: string;
   private readonly apiBase = "https://api.linkedin.com/v2";
   private publishRetryAttempts: number;
 
@@ -22,27 +23,35 @@ export class LinkedInService implements OnModuleInit {
 
   onModuleInit(): void {
     const accessToken = this.config.get<string>("app.linkedin.accessToken");
-    const personUrn = this.config.get<string>("app.linkedin.personUrn");
+    const authorUrn = this.config.get<string>("app.linkedin.authorUrn");
 
-    if (!accessToken || !personUrn) {
+    if (!accessToken || !authorUrn) {
       this.logger.warn(
         "LinkedIn credentials not configured — skipping client init",
       );
       return;
     }
 
     this.accessToken = accessToken;
-    this.personUrn = personUrn;
+    this.authorUrn = authorUrn;
     this.publishRetryAttempts =
       this.config.get<number>("app.scheduler.publishRetryAttempts") ?? 3;
-    this.logger.log("LinkedIn service initialized");
+    const authorType = this.authorUrn.startsWith("urn:li:organization:")
+      ? "organization"
+      : "member";
+    this.logger.log(`LinkedIn service initialized for ${authorType} author`);
+    if (authorType === "organization") {
+      this.logger.log(
+        "Organization posting requires org-scoped LinkedIn permissions and a page role for the authenticated member",
+      );
+    }
   }
 
   async createPost(content: string): Promise<SocialPostResult> {
     this.logger.log("Publishing post to LinkedIn...");
 
     const body = {
-      author: this.personUrn,
+      author: this.authorUrn,
       lifecycleState: "PUBLISHED",
       specificContent: {
         "com.linkedin.ugc.ShareContent": {
@@ -81,7 +90,7 @@ export class LinkedInService implements OnModuleInit {
           postedAt: new Date(),
         };
       } catch (error) {
-        lastError = error instanceof Error ? error.message : String(error);
+        lastError = this.describePublishError(error);
         this.logger.warn(
           `LinkedIn publish attempt ${attempt}/${this.publishRetryAttempts} failed: ${lastError}`,
         );
@@ -103,4 +112,18 @@ export class LinkedInService implements OnModuleInit {
   private delay(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+
+  private describePublishError(error: unknown): string {
+    if (error instanceof AxiosError) {
+      const status = error.response?.status;
+      const details =
+        typeof error.response?.data === "string"
+          ? error.response.data
+          : JSON.stringify(error.response?.data);
+
+      return status ? `HTTP ${status}${details ? ` — ${details}` : ""}` : error.message;
+    }
+
+    return error instanceof Error ? error.message : String(error);
+  }
 }

src/modules/scheduler/scheduler.service.ts

@@ -63,7 +63,7 @@ export class SchedulerService {
 
     this.linkedinEnabled = !!(
       this.config.get("app.linkedin.accessToken") &&
-      this.config.get("app.linkedin.personUrn")
+      this.config.get("app.linkedin.authorUrn")
     );
 
     this.twitterEnabled = !!(