@shipstatic/types 2.25.0 → 2.26.0-beta.2

package/dist/index.d.ts

@@ -135,7 +135,7 @@ export interface Deployment {
     readonly created: number;
     /** Unix timestamp (seconds) when deployment expires, null if never */
     expires: number | null;
-    /** Full URL to the deployment screenshot (e.g., 'https://screenshots.shipstatic.com/happy-cat-abc1234/a3f2c1b4d5e6f789') */
+    /** Full URL to the deployment screenshot, rendered on the first request for it (e.g., 'https://screenshots.shipstatic.com/happy-cat-abc1234/a3f2c1b4d5e6f789') */
     readonly screenshot: string;
 }
 /**
@@ -1793,6 +1793,38 @@ export declare const MY_API_KEY_URL = "https://my.shipstatic.com/api-key";
  * it is.
  */
 export declare const PUBLIC_DEPLOYMENT_TTL_SECONDS: number;
+/**
+ * A span of time in words: `"3 days"`, `"5 hours"`, `"45 minutes"`.
+ *
+ * Minutes under two hours, hours under two days, and days beyond, each rounded
+ * to the nearest. The unit changes exactly where the larger one rounds to two,
+ * so the number never jumps as time passes (119 minutes, then 2 hours), and
+ * the two vaguest things a rounded clock can say, "1 hour" and "1 day", are
+ * never said. Rounding rather than truncating is what lets a deployment made a
+ * second ago read the lifetime it was given: "3 days", not "2 days". Days are
+ * the largest unit because nobody counts a deadline in weeks, and a month has
+ * no fixed length.
+ *
+ * A span that rounds to no minutes at all, zero and negative included, reads
+ * "less than a minute".
+ */
+export declare function formatDuration(seconds: number): string;
+/**
+ * The time left before a deadline, in words (`"3 days"`), or `null` once it
+ * has passed.
+ *
+ * `expires` is unix SECONDS, the wire's own field, taken as it arrives so that
+ * no caller converts it: the deploy card once read it as a date string and
+ * showed the same three days on every deployment for months. `now` is seconds
+ * too, and defaults to the clock.
+ *
+ * A surface that tells a person how long a deployment has left says it with
+ * this, so one deployment reads the same everywhere, whenever it is looked at.
+ * What a surface says around the words is its own ("Expires in", "It stays
+ * live for"), and so is what it says once the deadline has passed, which is
+ * why that case is `null` rather than a sentence.
+ */
+export declare function formatTimeRemaining(expires: number, now?: number): string | null;
 /**
  * Universal deploy input — the union of every shape the SDK accepts.
  *

package/dist/index.js

@@ -1725,6 +1725,57 @@ export const MY_API_KEY_URL = 'https://my.shipstatic.com/api-key';
  */
 export const PUBLIC_DEPLOYMENT_TTL_SECONDS = 3 * 24 * 60 * 60;
 // =============================================================================
+// TIME REMAINING
+// =============================================================================
+/**
+ * A span of time in words: `"3 days"`, `"5 hours"`, `"45 minutes"`.
+ *
+ * Minutes under two hours, hours under two days, and days beyond, each rounded
+ * to the nearest. The unit changes exactly where the larger one rounds to two,
+ * so the number never jumps as time passes (119 minutes, then 2 hours), and
+ * the two vaguest things a rounded clock can say, "1 hour" and "1 day", are
+ * never said. Rounding rather than truncating is what lets a deployment made a
+ * second ago read the lifetime it was given: "3 days", not "2 days". Days are
+ * the largest unit because nobody counts a deadline in weeks, and a month has
+ * no fixed length.
+ *
+ * A span that rounds to no minutes at all, zero and negative included, reads
+ * "less than a minute".
+ */
+export function formatDuration(seconds) {
+    const minutes = Math.round(seconds / 60);
+    if (!(minutes >= 1))
+        return 'less than a minute';
+    if (minutes < 120)
+        return countOf(minutes, 'minute');
+    const hours = Math.round(seconds / 3_600);
+    if (hours < 48)
+        return countOf(hours, 'hour');
+    return countOf(Math.round(seconds / 86_400), 'day');
+}
+/**
+ * The time left before a deadline, in words (`"3 days"`), or `null` once it
+ * has passed.
+ *
+ * `expires` is unix SECONDS, the wire's own field, taken as it arrives so that
+ * no caller converts it: the deploy card once read it as a date string and
+ * showed the same three days on every deployment for months. `now` is seconds
+ * too, and defaults to the clock.
+ *
+ * A surface that tells a person how long a deployment has left says it with
+ * this, so one deployment reads the same everywhere, whenever it is looked at.
+ * What a surface says around the words is its own ("Expires in", "It stays
+ * live for"), and so is what it says once the deadline has passed, which is
+ * why that case is `null` rather than a sentence.
+ */
+export function formatTimeRemaining(expires, now = Date.now() / 1_000) {
+    const seconds = expires - now;
+    return seconds > 0 ? formatDuration(seconds) : null;
+}
+function countOf(count, unit) {
+    return `${count} ${unit}${count === 1 ? '' : 's'}`;
+}
+// =============================================================================
 // FILE UPLOAD TYPES
 // =============================================================================
 /**

package/dist/schemas.js

@@ -75,7 +75,7 @@ export const DeploymentSchema = z.object({
         .describe(`Unix timestamp (seconds) when the deployment expires; null when permanent. Anonymous deployments expire ${PUBLIC_DEPLOYMENT_TTL_SECONDS / 86_400} days after creation unless claimed; an authenticated deployment carries one only when it requested a ttl.`),
     screenshot: z
         .url()
-        .describe('Full URL to the deployment screenshot. Captured asynchronously after deploy; the URL is returned immediately but the image may take a few seconds to become available.'),
+        .describe('Full URL to the deployment screenshot. Rendered on the first request for it, so the URL is returned immediately and the first request takes a few seconds; every request after that is served immediately.'),
 });
 export const DeploymentCreateResponseSchema = DeploymentSchema.extend({
     claim: z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.25.0",
+  "version": "2.26.0-beta.2",
   "description": "Shared TypeScript types for the ShipStatic platform.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -144,7 +144,7 @@ export interface Deployment {
   readonly created: number;
   /** Unix timestamp (seconds) when deployment expires, null if never */
   expires: number | null; // Mutable - can be updated
-  /** Full URL to the deployment screenshot (e.g., 'https://screenshots.shipstatic.com/happy-cat-abc1234/a3f2c1b4d5e6f789') */
+  /** Full URL to the deployment screenshot, rendered on the first request for it (e.g., 'https://screenshots.shipstatic.com/happy-cat-abc1234/a3f2c1b4d5e6f789') */
   readonly screenshot: string;
 }
 
@@ -2646,6 +2646,61 @@ export const MY_API_KEY_URL = 'https://my.shipstatic.com/api-key';
  */
 export const PUBLIC_DEPLOYMENT_TTL_SECONDS = 3 * 24 * 60 * 60;
 
+// =============================================================================
+// TIME REMAINING
+// =============================================================================
+
+/**
+ * A span of time in words: `"3 days"`, `"5 hours"`, `"45 minutes"`.
+ *
+ * Minutes under two hours, hours under two days, and days beyond, each rounded
+ * to the nearest. The unit changes exactly where the larger one rounds to two,
+ * so the number never jumps as time passes (119 minutes, then 2 hours), and
+ * the two vaguest things a rounded clock can say, "1 hour" and "1 day", are
+ * never said. Rounding rather than truncating is what lets a deployment made a
+ * second ago read the lifetime it was given: "3 days", not "2 days". Days are
+ * the largest unit because nobody counts a deadline in weeks, and a month has
+ * no fixed length.
+ *
+ * A span that rounds to no minutes at all, zero and negative included, reads
+ * "less than a minute".
+ */
+export function formatDuration(seconds: number): string {
+  const minutes = Math.round(seconds / 60);
+  if (!(minutes >= 1)) return 'less than a minute';
+  if (minutes < 120) return countOf(minutes, 'minute');
+  const hours = Math.round(seconds / 3_600);
+  if (hours < 48) return countOf(hours, 'hour');
+  return countOf(Math.round(seconds / 86_400), 'day');
+}
+
+/**
+ * The time left before a deadline, in words (`"3 days"`), or `null` once it
+ * has passed.
+ *
+ * `expires` is unix SECONDS, the wire's own field, taken as it arrives so that
+ * no caller converts it: the deploy card once read it as a date string and
+ * showed the same three days on every deployment for months. `now` is seconds
+ * too, and defaults to the clock.
+ *
+ * A surface that tells a person how long a deployment has left says it with
+ * this, so one deployment reads the same everywhere, whenever it is looked at.
+ * What a surface says around the words is its own ("Expires in", "It stays
+ * live for"), and so is what it says once the deadline has passed, which is
+ * why that case is `null` rather than a sentence.
+ */
+export function formatTimeRemaining(
+  expires: number,
+  now: number = Date.now() / 1_000,
+): string | null {
+  const seconds = expires - now;
+  return seconds > 0 ? formatDuration(seconds) : null;
+}
+
+function countOf(count: number, unit: string): string {
+  return `${count} ${unit}${count === 1 ? '' : 's'}`;
+}
+
 // =============================================================================
 // RESOURCE INTERFACE CONTRACTS
 // =============================================================================

package/src/schemas.ts

@@ -94,7 +94,7 @@ export const DeploymentSchema = z.object({
   screenshot: z
     .url()
     .describe(
-      'Full URL to the deployment screenshot. Captured asynchronously after deploy; the URL is returned immediately but the image may take a few seconds to become available.',
+      'Full URL to the deployment screenshot. Rendered on the first request for it, so the URL is returned immediately and the first request takes a few seconds; every request after that is served immediately.',
     ),
 });