Star Micronics Integration

Overview

Star Micronics is a cloud printing integration that connects Upvendo to Star Micronics cloud printers via the Star Micronics Cloud platform. It uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authentication, allowing Upvendo to manage printer configurations, devices, and receipt printing through the Star Micronics Cloud API. The integration is implemented as both a Socialite provider (for the OAuth flow) and a standalone service (for direct API interaction).

Purpose

This integration lets you connect Star Micronics cloud printers to Upvendo for remote receipt printing through the Star Micronics Cloud platform.

Key Concepts

• OAuth 2.0 with PKCE: The integration uses the authorization code flow with PKCE (S256 code challenge method) for authentication. No client secret is required -- only a client ID and a dynamically generated code verifier/challenge pair.
• Star Micronics Cloud: The cloud platform at starmicronicscloud.com manages printer fleets. Upvendo authenticates to access printer configurations, device lists, and receipt submission endpoints.
• Socialite Provider: A custom Laravel Socialite provider (StarMicronicsProvider) handles the OAuth redirect and callback flows, integrating with Laravel's standard authentication pipeline.
• CloudPRNT: Star Micronics' cloud printing protocol that enables printers to poll for and print jobs remotely without direct network access to the printer.
• Token Management: Access tokens and refresh tokens are obtained through the OAuth flow and stored for ongoing API access. The service supports token refresh to maintain long-lived sessions.

Prerequisites

• A Star Micronics Cloud account at account.starmicronicscloud.com
• A Star Micronics cloud-capable printer (models supporting CloudPRNT)
• The printer must be registered and online in the Star Micronics Cloud platform
• Star Micronics client ID configured in Upvendo's environment (services.star_micronics.client_id)
• Star Micronics redirect URI configured in Upvendo's environment (services.star_micronics.redirect_uri)

Setup Steps

Step 1: Configure Environment

Ensure the following environment variables are set in the Upvendo backend configuration:

• STAR_MICRONICS_CLIENT_ID -- Your Star Micronics Cloud application client ID
• STAR_MICRONICS_REDIRECT_URI -- The callback URL for OAuth (e.g., https://your-domain.com/auth/star-micronics/callback)

Step 2: Initiate OAuth Connection

1. Navigate to the Star Micronics connection page
2. Click Connect to Star Micronics
3. You are redirected to account.starmicronicscloud.com for authorization
4. The system generates a PKCE code verifier and code challenge (S256)
5. Log in to your Star Micronics Cloud account and authorize Upvendo

Step 3: Complete OAuth Callback

1. After authorization, Star Micronics redirects back to Upvendo
2. The system exchanges the authorization code for access and refresh tokens
3. Tokens are stored securely for ongoing API access
4. A success message confirms the connection: "Successfully connected to Star Micronics"

Step 4: Verify Printer Access

1. Confirm that your printers appear in the device management section
2. Test printing by sending a test receipt
3. Verify the printer is online and receiving print jobs

Data Sync Details

What Syncs

Star Micronics Data	Upvendo Usage	Notes
Printer Configurations	Device settings	Managed via Cloud API
Device List	Available printers	Printers registered in the cloud
Receipt Jobs	Print queue	Receipts sent for printing

Sync Direction

• Upvendo to Star Micronics: Receipt data and print jobs are pushed from Upvendo to Star Micronics Cloud for printing.
• Star Micronics to Upvendo: Printer status and configuration data can be read from the Star Micronics Cloud API.

Conflict Resolution

Not applicable -- receipt printing is a one-way push operation. Each print job is independent.

Actions

Connect

• OAuth Redirect: The Socialite provider redirects to https://account.starmicronicscloud.com/signin/oauth2/v2.0/authorize with PKCE parameters
• OAuth Callback: The callback exchanges the authorization code at https://account.starmicronicscloud.com/signin/oauth2/v2.0/token using the stored code verifier
• Note: The web routes for Star Micronics auth are currently commented out in routes/web.php (/auth/star-micronics and /auth/star-micronics/callback), indicating this integration is in development or staging

Sync

• No periodic sync is needed -- printers are managed through the Star Micronics Cloud platform
• Print jobs are submitted on-demand when receipts need to be printed

Disconnect

• Remove stored tokens to disconnect from the Star Micronics Cloud platform
• Printers will stop receiving print jobs from Upvendo

Fields

Configuration (environment variables)

Field	Type	Description
services.star_micronics.client_id	string	Star Micronics Cloud application client ID
services.star_micronics.redirect_uri	string	OAuth callback URL

OAuth Token Response

Field	Type	Description
access_token	string	Bearer token for Star Micronics Cloud API
refresh_token	string	Token used to obtain new access tokens
token_type	string	Token type (typically Bearer)
expires_in	int	Token lifetime in seconds

OAuth Scopes

Scope	Description
https://starmicronicscloud.com/printer-manager/configurations	Access printer configurations
https://starmicronicscloud.com/printer-manager/devices	Access device (printer) list
https://starmicronicscloud.com/printer-manager/receipts	Submit and manage receipt print jobs

PKCE Parameters

Parameter	Value	Description
code_challenge_method	S256	SHA-256 hashed code challenge
code_verifier	string	64-character random string (base64url encoded)
code_challenge	string	SHA-256 hash of verifier (base64url encoded)

Business Rules

• The PKCE code verifier is stored temporarily (10 minutes in the service, or in session via the Socialite provider) and must be available when the callback is processed.
• The integration uses two parallel implementations: StarMicronicsService (standalone, stores code verifier in MongoDB cache) and StarMicronicsProvider (Socialite, stores code verifier in session).
• Token refresh is supported via the refreshToken() method on StarMicronicsService, which exchanges a refresh token for new access/refresh tokens.
• The Star Micronics auth routes are currently commented out in production, suggesting this integration may be in a pre-release or testing phase.
• No client secret is used -- PKCE replaces the client secret for public client authentication.

FAQs

What printer models are supported?

Any Star Micronics printer that supports CloudPRNT and is registered in the Star Micronics Cloud platform. Common models include the mC-Print2, mC-Print3, and TSP100IV series.

Do I need a Star Micronics Cloud account?

Yes. You need an account at account.starmicronicscloud.com with your printers registered and configured.

How does PKCE authentication work?

PKCE (Proof Key for Code Exchange) is a security extension for OAuth 2.0. Instead of using a client secret, the system generates a random code verifier and its SHA-256 hash (code challenge). The challenge is sent with the authorization request, and the verifier is sent with the token exchange, proving that the same client initiated both requests.

Can I use this integration without cloud connectivity?

No. Star Micronics Cloud requires internet access on both the Upvendo server and the printer. For local-only printing, consider a direct USB or network printer setup instead.

Is this integration ready for production use?

The auth routes are currently commented out in routes/web.php, indicating this integration is in development or staging. Contact the development team for the current status.

Troubleshooting

"Code verifier not found" error during callback

The PKCE code verifier expired (10-minute timeout) or was not properly stored. Restart the OAuth flow by clicking "Connect to Star Micronics" again. Ensure the callback is processed within 10 minutes of initiating the authorization.

"Failed to get access token" error

The authorization code may have expired, the code verifier may not match, or the Star Micronics Cloud service may be experiencing issues. Check the Star Micronics Cloud status page and retry the connection.

"Failed to refresh token" error

The refresh token may have expired or been revoked. Re-authenticate by going through the full OAuth flow again.

Printer not receiving print jobs

Verify the printer is online in the Star Micronics Cloud dashboard. Check that the access token is still valid (tokens expire and may need refreshing). Ensure the printer is assigned to the correct Star Micronics Cloud account.

OAuth redirect not working

Verify that STAR_MICRONICS_CLIENT_ID and STAR_MICRONICS_REDIRECT_URI environment variables are correctly configured. The redirect URI must exactly match what is registered in the Star Micronics Cloud application settings.

Assistant Guidance

When a user asks about Star Micronics or cloud printing:

• Note that this integration is currently in development/staging -- the auth routes are commented out in production.
• If they need receipt printing now, suggest checking with the development team for the current status of this integration.
• For setup questions, explain the OAuth + PKCE flow and the requirement for a Star Micronics Cloud account.
• If they report token errors, the first step is always to re-authenticate via the OAuth flow.
• Clarify that this is for cloud printers only -- local USB/network printers do not use this integration.
• The two implementation paths (Socialite provider and standalone service) serve different purposes but achieve the same OAuth result.

Relations

Depends On

• Star Micronics Cloud platform (external service)
• Laravel Socialite (for OAuth provider implementation)
• Environment configuration (services.star_micronics.*)

Affects

• Receipt Printing (enables cloud-based receipt printing)
• Device Management (printers appear as managed devices)