newOS for Developers

Payment & Subscriptions

Stripe checkout and subscription management for newOS platform.

packages/newgraph-signals/src/actions/payment.ts

Subscription Tiers

Free

Free Tier

  • • Basic content creation
  • • Limited credits
  • • Standard features
newOS One

newOS One

  • • Unlimited content creation
  • • Full credit quota
  • • Premium features
  • • Priority support

Type Definitions

type PaymentState = {
  checkoutUrl: string;  // Stripe checkout URL to redirect
  status: string;       // Current payment status
};

stripeCheckoutSessionCreate

Create a Stripe checkout session for subscription payment.

stripeCheckoutSessionCreate(params?: { autostart: boolean })
  : ProgressiveHandlerResponse<Signal<PaymentState>>

// Execute with params:
{ priceId: string }  // Stripe Price ID
ParameterTypeRequiredDescription
priceIdstringYesStripe Price ID for subscription product

Checkout Flow

  1. Call with Stripe price ID
  2. API creates checkout session and returns URL
  3. Redirect user to checkoutUrl
  4. User completes payment on Stripe hosted page
  5. Stripe webhook updates user subscription status

Usage Example

import { stripeCheckoutSessionCreate } from "newgraph-signals/actions/payment";

const [paymentState, progress] = stripeCheckoutSessionCreate();

// Create checkout session
progress.value.exec({ priceId: "price_1QclmIKijqiCtsstf2dyEFS5" });
await progress.value.promise;

// Redirect to Stripe
if (paymentState.value.checkoutUrl) {
  window.location.href = paymentState.value.checkoutUrl;
}
API: api.payment.stripeCheckoutSessionCreate({ priceId })

magicSubscription

Special

Apply a magic spell code for free subscription access. Used for promotions and special access.

magicSubscription()
  : ProgressiveHandlerResponse<Signal<{ status: string }>>

// Execute with params:
{ spell: string }  // Magic activation code
ParameterTypeRequiredDescription
spellstringYesMagic code for subscription activation

Status Messages

Success

Returns server success status

Already Subscribed (400)

"As a subscriber, you already have all the magic in the world. Leave in peace."

Invalid Spell

"No magic for you. Go back to Hogwarts and don't return unless ready."

Usage Example

import { magicSubscription } from "newgraph-signals/actions/payment";

const [statusSignal, progress] = magicSubscription();

// Apply magic code
progress.value.exec({ spell: "NEWOS2024" });
await progress.value.promise;

if (statusSignal.value.status === "success") {
  console.log("Subscription activated!");
} else {
  console.log(statusSignal.value.status);
}
API: api.payment.magicCreate({ spell })

Underlying API

api.payment.stripeCheckoutSessionCreate({ priceId })

POST — Creates Stripe checkout session, returns checkout URL

api.payment.magicCreate({ spell })

POST — Applies magic subscription code

Stripe Payment Links

Alternative Flow

For static deployments (GitHub Pages), you can use Stripe Payment Links instead of checkout sessions. Configure Payment Links in Stripe Dashboard with success/cancel URLs pointing to your app. The Newgraph backend handles webhook updates to user subscription status.

// Static Payment Link flow (no serverless required)
const PAYMENT_LINK = "https://buy.stripe.com/your-payment-link";

function handleUpgrade() {
  window.location.href = PAYMENT_LINK;
}

// After returning from Stripe, check subscription status
import { current } from "newgraph-signals/actions/auth";
const user = await current();
console.log(user.subscription); // Updated by webhook

Credit System

Credit Quotas

newOS uses a credit-based system for AI operations and premium features. Free tier users have limited monthly credits, while newOS One subscribers have increased or unlimited quotas depending on the operation type.

Integration Notes

Stripe Configuration

Ensure your Stripe price IDs match the configured products. The checkout session redirects to Stripe's hosted payment page, then returns to your configured success/cancel URLs.

Webhook Handler

Stripe webhooks are handled by the Newgraph backend. After successful payment, the backend updates the user's subscription status. Frontend should refetch user data to reflect the updated subscription.