@tekrom/tsoft-app-gate 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +28 -5
- package/dist/client.d.ts +8 -1
- package/dist/client.js +5 -0
- package/dist/index.d.ts +1 -1
- package/dist/protocol.d.ts +13 -0
- package/dist/tsoft-app-gate.min.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -9,13 +9,13 @@ npm install @tekrom/tsoft-app-gate
|
|
|
9
9
|
Paketleyici kullanmıyorsanız tarayıcı derlemesini `<script>` ile yükleyin; aynı API `TSoftAppGate` global'i altında gelir:
|
|
10
10
|
|
|
11
11
|
```html
|
|
12
|
-
<script src="https://cdn.jsdelivr.net/npm/@tekrom/tsoft-app-gate@0.
|
|
12
|
+
<script src="https://cdn.jsdelivr.net/npm/@tekrom/tsoft-app-gate@0.4/dist/tsoft-app-gate.min.js"></script>
|
|
13
13
|
<script>
|
|
14
14
|
const app = TSoftAppGate.createApp();
|
|
15
15
|
</script>
|
|
16
16
|
```
|
|
17
17
|
|
|
18
|
-
Sürümü sabitleyin (`@0.
|
|
18
|
+
Sürümü sabitleyin (`@0.4` ya da tam sürüm); üretimde dosyayı kendi sunucunuzdan sunmak da mümkündür.
|
|
19
19
|
|
|
20
20
|
## Hızlı başlangıç
|
|
21
21
|
|
|
@@ -50,6 +50,11 @@ try {
|
|
|
50
50
|
|
|
51
51
|
await app.navigate.panel('order', 1042);
|
|
52
52
|
|
|
53
|
+
await app.nav.set([
|
|
54
|
+
{ label: 'Gönderiler', path: '/shipments' },
|
|
55
|
+
{ label: 'Ayarlar', path: '/settings' },
|
|
56
|
+
]);
|
|
57
|
+
|
|
53
58
|
const stop = app.autoResize();
|
|
54
59
|
```
|
|
55
60
|
|
|
@@ -118,6 +123,23 @@ Panelde başka bir sayfaya geçer (uygulama kapanır).
|
|
|
118
123
|
|
|
119
124
|
Kimlik `^[A-Za-z0-9_-]{1,64}$` kalıbına uymalı; bilinmeyen kaynak ya da geçersiz kimlik `invalid_route` döner.
|
|
120
125
|
|
|
126
|
+
### `nav.set(items)`
|
|
127
|
+
|
|
128
|
+
Panelin sol menüsünde (ve mobil menüde) uygulamanın adının altında alt menü gösterir; Shopify App Bridge'deki `ui-nav-menu` karşılığıdır. `items`: `{ label, path }` listesi.
|
|
129
|
+
|
|
130
|
+
- En fazla 8 öğe; `label` boş olamaz, en fazla 40 karakter.
|
|
131
|
+
- `path` uygulamanın kendi adresi altında, `/` ile başlayan yol olmalı (`/orders?status=1` gibi). Mutlak ya da başka origin'e giden adres, `//` ile başlayan yol ve `javascript:` reddedilir. `app_url` bir alt dizindeyse (`https://x.com/app/`) yol o dizinin altında kalmalı.
|
|
132
|
+
- Tek bir geçersiz öğe bütün listeyi `invalid_payload` ile reddeder; menü değişmez.
|
|
133
|
+
- Boş liste (`[]`) menüyü kaldırır.
|
|
134
|
+
|
|
135
|
+
Bağlantıya tıklanınca panel `?path=` değerini değiştirir ve iframe'i o yolla, yeni oturum token'ıyla yeniden yükler. Etkin bağlantı iframe'in o anki yoluna göre işaretlenir: önce bire bir eşleşme, sonra en uzun yol öneki (`/orders` bağlantısı `/orders/42` yolunda da etkin; `/` yalnız kendisiyle eşleşir). Uygulama kendi içinde gezindikçe `navigate.app` çağırırsa vurgu da güncel kalır.
|
|
136
|
+
|
|
137
|
+
Panel son gönderilen listeyi uygulama başına tarayıcıda saklar; menü bir sonraki açılışta uygulama yüklenmeden görünür. Alt menü uygulama panelde açıkken ya da menüye sabitlenmişken görünür. Listeyi her açılışta göndermeniz yeterlidir:
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
await app.nav.set([{ label: 'Gönderiler', path: '/shipments' }, { label: 'Ayarlar', path: '/settings' }]);
|
|
141
|
+
```
|
|
142
|
+
|
|
121
143
|
### `pickResource({ type, multiple? })`
|
|
122
144
|
|
|
123
145
|
Panelin seçicisini açar, seçilen kayıtların kimliklerini döner: `{ ids, cancelled }`. Kullanıcı pencereyi kapatırsa `{ ids: [], cancelled: true }`. Varsayılan olarak zaman aşımı yoktur.
|
|
@@ -148,7 +170,7 @@ Tüm reddedilen promise'ler `AppBridgeError` taşır; `code` alanı aşağıdaki
|
|
|
148
170
|
|
|
149
171
|
| Kod | Kaynak | Anlamı |
|
|
150
172
|
|---|---|---|
|
|
151
|
-
| `invalid_payload` | panel | Zorunlu alan boş ya da tipi yanl
|
|
173
|
+
| `invalid_payload` | panel | Zorunlu alan boş ya da tipi yanlış; `nav.set` listesinde geçersiz öğe. |
|
|
152
174
|
| `invalid_path` | panel | `navigate.app` yolu geçersiz ya da uygulama origin'i dışında. |
|
|
153
175
|
| `invalid_route` | panel | `navigate.panel` kaynağı bilinmiyor ya da kimlik geçersiz. |
|
|
154
176
|
| `missing_scope` | panel | Uygulamanın bu iş için gereken kapsamı yok. |
|
|
@@ -169,7 +191,7 @@ Panel uygulamanın `app_url` adresini (yalnız `https`, panel origin'inden farkl
|
|
|
169
191
|
|
|
170
192
|
- `session`: Oturum JWT'si.
|
|
171
193
|
- `code`: Yalnız kurulumdan hemen sonraki ilk açılışta, kurulum kodu.
|
|
172
|
-
- Panel URL'inde `?path=/x` varsa uygulama `app_url` origin'i altındaki `/x` yolundan açılır.
|
|
194
|
+
- Panel URL'inde `?path=/x` varsa uygulama `app_url` origin'i altındaki `/x` yolundan açılır. `?path=` panel tarafında değişirse (alt menü bağlantısı) iframe o yolla yeniden yüklenir; `navigate.app`'in yazdığı yol yeniden yükleme yapmaz.
|
|
173
195
|
|
|
174
196
|
iframe `sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-downloads"`, `allow="clipboard-write"` ve `referrerpolicy="strict-origin"` ile açılır. Üst pencereye yönlendirme (`allow-top-navigation`) yoktur; panelde gezinmek için `navigate.panel` kullanılır.
|
|
175
197
|
|
|
@@ -206,6 +228,7 @@ Kurallar:
|
|
|
206
228
|
| `navigate.panel` | `{ resource, id? }` | `{}` | `invalid_route` |
|
|
207
229
|
| `resource.pick` | `{ type, multiple? }` | `{ ids, cancelled? }` | `unsupported_resource`, `missing_scope` |
|
|
208
230
|
| `size.set` | `{ height }` | `{}` | `invalid_payload` |
|
|
231
|
+
| `nav.set` | `{ items: [{ label, path }] }` | `{}` | `invalid_payload` |
|
|
209
232
|
| diğer | — | — | `unsupported_type` |
|
|
210
233
|
|
|
211
234
|
`confirm.open` ve `resource.pick` yanıtı kullanıcı işlem yapınca gelir.
|
|
@@ -241,7 +264,7 @@ Script panel dışında açılınca ilk istekte hata veriyordu; `createApp()` is
|
|
|
241
264
|
|
|
242
265
|
### 0.1.x'ten
|
|
243
266
|
|
|
244
|
-
0.1.x'teki `createApp({ apiKey, shopId, host })`, `setNavigationMenu` ve `showToast` panelin tanımadığı bir mesaj biçimi (`T_SOFT_APP_BRIDGE`) gönderiyordu; kaldırıldı. `showToast(app, opts)` yerine `app.toast(message, opts)` kullanın;
|
|
267
|
+
0.1.x'teki `createApp({ apiKey, shopId, host })`, `setNavigationMenu` ve `showToast` panelin tanımadığı bir mesaj biçimi (`T_SOFT_APP_BRIDGE`) gönderiyordu; kaldırıldı. `showToast(app, opts)` yerine `app.toast(message, opts)` kullanın; `setNavigationMenu` yerine 0.4.0'dan beri `app.nav.set(items)` var.
|
|
245
268
|
|
|
246
269
|
## Geliştirme
|
|
247
270
|
|
package/dist/client.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type BridgeErrorCode, type PanelDetailResource, type PanelListResource, type PickableResource, type RequestPayloads, type RequestType, type ResponsePayloads, type ToastVariant } from './protocol.js';
|
|
1
|
+
import { type BridgeErrorCode, type NavItem, type PanelDetailResource, type PanelListResource, type PickableResource, type RequestPayloads, type RequestType, type ResponsePayloads, type ToastVariant } from './protocol.js';
|
|
2
2
|
export declare class AppBridgeError extends Error {
|
|
3
3
|
readonly code: BridgeErrorCode;
|
|
4
4
|
constructor(code: BridgeErrorCode, message?: string);
|
|
@@ -82,6 +82,13 @@ export interface App {
|
|
|
82
82
|
panel(resource: PanelListResource, options?: RequestOptions): Promise<void>;
|
|
83
83
|
panel(resource: PanelDetailResource, id: string | number, options?: RequestOptions): Promise<void>;
|
|
84
84
|
};
|
|
85
|
+
nav: {
|
|
86
|
+
/**
|
|
87
|
+
* Panelin sol menüsünde uygulamanın altındaki bağlantıları ayarlar (en fazla 8).
|
|
88
|
+
* Tıklanan bağlantı iframe'i o yolla yeniden yükler; panel listeyi tarayıcıda saklar.
|
|
89
|
+
*/
|
|
90
|
+
set(items: NavItem[], options?: RequestOptions): Promise<void>;
|
|
91
|
+
};
|
|
85
92
|
/** Panelin seçicisini açar. Varsayılan olarak zaman aşımı yoktur. */
|
|
86
93
|
pickResource(options: PickOptions): Promise<PickResult>;
|
|
87
94
|
/** iframe yüksekliğini ayarlar; panel 300–5000 px aralığına sıkıştırır. */
|
package/dist/client.js
CHANGED
|
@@ -160,6 +160,11 @@ export function createApp(options = {}) {
|
|
|
160
160
|
return empty('navigate.panel', { resource }, idOrOptions);
|
|
161
161
|
},
|
|
162
162
|
},
|
|
163
|
+
nav: {
|
|
164
|
+
set(items, requestOptions) {
|
|
165
|
+
return empty('nav.set', { items: items.map(({ label, path }) => ({ label, path })) }, requestOptions);
|
|
166
|
+
},
|
|
167
|
+
},
|
|
163
168
|
async pickResource({ type, multiple, ...rest }) {
|
|
164
169
|
const response = await request('resource.pick', { type, multiple: multiple === true }, rest, 0);
|
|
165
170
|
return { ids: Array.isArray(response.ids) ? response.ids : [], cancelled: response.cancelled === true };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
export { createApp, isEmbedded, decodeSessionToken, AppBridgeError, PANEL_ORIGIN_PATTERN } from './client.js';
|
|
2
2
|
export type { App, AppOptions, AutoResizeOptions, ConfirmOptions, PickOptions, PickResult, RequestOptions, SessionClaims, SessionToken, ToastOptions, } from './client.js';
|
|
3
3
|
export { BRIDGE_VERSION, APP_SOURCE, PANEL_SOURCE } from './protocol.js';
|
|
4
|
-
export type { BridgeErrorCode, BridgeRequest, BridgeResponse, PanelDetailResource, PanelListResource, PanelResource, PickableResource, RequestPayloads, RequestType, ResponsePayloads, ToastVariant, } from './protocol.js';
|
|
4
|
+
export type { BridgeErrorCode, BridgeRequest, BridgeResponse, NavItem, PanelDetailResource, PanelListResource, PanelResource, PickableResource, RequestPayloads, RequestType, ResponsePayloads, ToastVariant, } from './protocol.js';
|
package/dist/protocol.d.ts
CHANGED
|
@@ -32,6 +32,15 @@ export type PanelDetailResource = 'order' | 'product';
|
|
|
32
32
|
export type PanelResource = PanelListResource | PanelDetailResource;
|
|
33
33
|
/** Seçici türü ve istediği kapsam: `product` → `read_products`. */
|
|
34
34
|
export type PickableResource = 'product';
|
|
35
|
+
/**
|
|
36
|
+
* Panelin sol menüsünde uygulamanın adı altında görünen bağlantı. `path` uygulamanın
|
|
37
|
+
* kendi adresi altında `/` ile başlayan yol olmalı (`/orders?status=1` gibi); etiket
|
|
38
|
+
* en fazla 40 karakter. Liste en fazla 8 öğe; boş liste menüyü kaldırır.
|
|
39
|
+
*/
|
|
40
|
+
export interface NavItem {
|
|
41
|
+
label: string;
|
|
42
|
+
path: string;
|
|
43
|
+
}
|
|
35
44
|
export interface RequestPayloads {
|
|
36
45
|
'session-token.get': Record<string, never>;
|
|
37
46
|
'toast.show': {
|
|
@@ -57,6 +66,9 @@ export interface RequestPayloads {
|
|
|
57
66
|
'size.set': {
|
|
58
67
|
height: number;
|
|
59
68
|
};
|
|
69
|
+
'nav.set': {
|
|
70
|
+
items: NavItem[];
|
|
71
|
+
};
|
|
60
72
|
}
|
|
61
73
|
export interface ResponsePayloads {
|
|
62
74
|
'session-token.get': {
|
|
@@ -75,6 +87,7 @@ export interface ResponsePayloads {
|
|
|
75
87
|
cancelled?: boolean;
|
|
76
88
|
};
|
|
77
89
|
'size.set': Record<string, never>;
|
|
90
|
+
'nav.set': Record<string, never>;
|
|
78
91
|
}
|
|
79
92
|
export type RequestType = keyof RequestPayloads;
|
|
80
93
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
"use strict";var TSoftAppGate=(()=>{var
|
|
1
|
+
"use strict";var TSoftAppGate=(()=>{var E=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var D=Object.getOwnPropertyNames;var U=Object.prototype.hasOwnProperty;var z=(o,n)=>{for(var i in n)E(o,i,{get:n[i],enumerable:!0})},V=(o,n,i,u)=>{if(n&&typeof n=="object"||typeof n=="function")for(let a of D(n))!U.call(o,a)&&a!==i&&E(o,a,{get:()=>n[a],enumerable:!(u=L(n,a))||u.enumerable});return o};var G=o=>V(E({},"__esModule",{value:!0}),o);var H={};z(H,{APP_SOURCE:()=>T,AppBridgeError:()=>p,BRIDGE_VERSION:()=>P,PANEL_ORIGIN_PATTERN:()=>S,PANEL_SOURCE:()=>O,createApp:()=>B,decodeSessionToken:()=>x,isEmbedded:()=>b});var P=1,T="tsoft-app",O="tsoft-panel";var p=class extends Error{constructor(n,i){super(i!=null?i:`T-Soft App Bridge: ${n}`),this.name="AppBridgeError",this.code=n}},M=1e4,F=15e3,S=/^https:\/\/([a-z0-9-]+\.)*(tsoftpanel\.com|tsoftpanel\.net|paneltsoft\.com)$/;function b(){return typeof window!="undefined"&&window.parent!==window}function j(){let o=window.location.ancestorOrigins;if(o&&o.length>0)return o[0];try{return document.referrer?new URL(document.referrer).origin:null}catch(n){return null}}function x(o){try{let n=atob(o.split(".")[1].replace(/-/g,"+").replace(/_/g,"/")),i=JSON.parse(new TextDecoder().decode(Uint8Array.from(n,u=>u.charCodeAt(0))));return i&&typeof i.exp=="number"?i:null}catch(n){return null}}function $(o){return o!==null&&o.expiresAt-F>Date.now()}function B(o={}){var h,_;if(!b())throw new p("not_embedded","T-Soft App Bridge: uygulama panel iframe'i i\xE7inde a\xE7\u0131lmam\u0131\u015F");let n=o.panelOrigin?null:j();if(!o.panelOrigin&&!(n&&S.test(n)))throw new p("not_embedded",`T-Soft App Bridge: \xFCst pencere bir T-Soft paneli de\u011Fil (${n!=null?n:"bilinmiyor"})`);let i=(h=o.panelOrigin)!=null?h:n,u=(_=o.timeout)!=null?_:M,a=new Map,k=new URLSearchParams(window.location.search),v=k.get("session"),I=0,A=!1,l=null,R=null;if(v){let t=x(v);t&&(l={token:v,claims:t,expiresAt:t.exp*1e3,scopes:null})}function w(t){var r;if(t.source!==window.parent||t.origin!==i)return;let e=t.data;if((e==null?void 0:e.source)!==O||(e==null?void 0:e.version)!==1||typeof(e==null?void 0:e.id)!="string")return;let s=a.get(e.id);s&&(a.delete(e.id),clearTimeout(s.timer),e.ok===!0?s.resolve((r=e.payload)!=null?r:{}):s.reject(new p(typeof e.error=="string"?e.error:"internal_error")))}window.addEventListener("message",w);function d(t,e,s={},r=u){var y;if(A)return Promise.reject(new p("destroyed"));let c=`app-${Date.now().toString(36)}-${(I++).toString(36)}`,g=(y=s.timeout)!=null?y:r;return new Promise((f,C)=>{let N={resolve:f,reject:C};g>0&&(N.timer=setTimeout(()=>{a.delete(c),C(new p("timeout"))},g)),a.set(c,N),window.parent.postMessage({source:T,version:1,id:c,type:t,payload:e},i)})}async function q(t={}){return!t.forceRefresh&&$(l)?l:(R!=null||(R=d("session-token.get",{},t).then(e=>(l={token:e.token,claims:x(e.token),expiresAt:Date.now()+e.expires_in*1e3,scopes:Array.isArray(e.scopes)?e.scopes:[]},l)).finally(()=>{R=null})),R)}async function m(t,e,s){await d(t,e,s)}return{panelOrigin:i,get claims(){var t;return(t=l==null?void 0:l.claims)!=null?t:null},installCode:k.get("code"),getSession:q,async getSessionToken(t){return(await q(t)).token},toast(t,{variant:e,...s}={}){return m("toast.show",e?{message:t,variant:e}:{message:t},s)},async confirm(t){let{message:e,title:s,confirmText:r,...c}=typeof t=="string"?{message:t}:t;return(await d("confirm.open",{message:e,title:s,confirmText:r},c,0)).confirmed===!0},navigate:{app(t,e){return m("navigate.app",{path:t},e)},panel(t,e,s){return typeof e=="string"||typeof e=="number"?m("navigate.panel",{resource:t,id:String(e)},s):m("navigate.panel",{resource:t},e)}},nav:{set(t,e){return m("nav.set",{items:t.map(({label:s,path:r})=>({label:s,path:r}))},e)}},async pickResource({type:t,multiple:e,...s}){let r=await d("resource.pick",{type:t,multiple:e===!0},s,0);return{ids:Array.isArray(r.ids)?r.ids:[],cancelled:r.cancelled===!0}},setHeight(t,e){return m("size.set",{height:Math.ceil(t)},e)},autoResize({target:t}={}){let e=t!=null?t:document.body,s=0,r=0,c=()=>{r=0;let y=getComputedStyle(e),f=Math.ceil(e.getBoundingClientRect().height+parseFloat(y.marginTop)+parseFloat(y.marginBottom));f!==s&&(s=f,d("size.set",{height:f}).catch(()=>{}))},g=new ResizeObserver(()=>{r||(r=requestAnimationFrame(c))});return g.observe(e),()=>{g.disconnect(),r&&cancelAnimationFrame(r)}},request:d,destroy(){A=!0,window.removeEventListener("message",w);for(let t of a.values())clearTimeout(t.timer),t.reject(new p("destroyed"));a.clear()}}}return G(H);})();
|